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Preface 



Preface xvH 



For your convenience and ease of reference, this manual is divided into 
two volumes. Volume 1 : How SOS Works describes the operating system 
of the Apple III. Volume 2: The SOS Calls defines the individual SOS calls. 
Notice that the sequence of ctiapter numbers in Volume 1 continues 
unchanged into Volume 2. 

Scope of this Manual 



This manual describes SOS (pronounced "sauce"), the Sophisticated 
Operating System of the Apple III. With the information in this manual 
you'll be able to write assembly-language programs that use the full 
power of the Apple 111. 

However, this manual is not a course in assembly-language programming. 
It assumes that you can program in assembly language and know the 
architecture of the 6502 microprocessor upon which the Apple 111 is 
based; it will explain tiow the architecture of the Apple III processor goes 
beyond that of the standard 6502. If you need more information on 6502 
assembly-language programming, refer to one of the books listed in the 
bibliography of this manual. 

The companion volume to this manual, the Apple III SOS Device Driver 
Writer's Guide, contains the information you may need about the inter face 
hardware of the Apple III, and tells how to create device drivers to use that 
hardware. If you wish to create custom interface software or hardware for 
the Apple III, read the present manual before turning to the Appte III SOS 
Device Driver Writer's Guide. 
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Using this Manual 



Before you begin with this manual, you should prepare yourself by 
reading the following; 

• the Apple III Owner's Guide introduces you to some of the 
fundamental features of the Apple III— features that you will 
be exploring more deeply in this manual; 

• the Apple III Standard Device Drivers Manual describes the 
workings of the Apple til's video screen, keyboard, graphics, 
and communications interfaces; 

• the Apple III Pascal Program Preparation Toots manual explains 
the use of the Apple III Pascal Assembler, which is the only 
assembler that works with SOS. 

You should also finish reading this preface, to learn about the notation and 
examples used in this manual. 

About the Exampies 



Included in this manual are many sample programs and code fragments. 
These are intended as demonstrations only. In order to illustrate their 
concepts as well as possible, they are written to be clear and concise, 
without necessarily being efficient or comprehensive. 

Notation and Symbols 



Some special symbols and numeric notations are used throughout this 
manual. 



Numeric Notation 

We assume that you are familiar with the hexadecimal (hex) numbering 
system. All hexadecimal numbers in the text and tables of this manual are 
preceded by a dollarsign {$}. Any number in the text, a table, or 
illustration that is not preceded by a dollar sign is a decimal number. 



Program listings from the Apple III Pascal Assembfer, however, do not 
prefix hex numbers with dollar signs, fn such listings, you can distinguish 
decimal numbers from hex by the fact that decimal numbers end with a 
decimal point (. ). You can distinguish hex numbers from labels by the fact 
that hex numbers always begin with a digit from to 9, and labels always 
begin with a letter. 

Type Notation in Text Notation in Listings 



Decimal 255 

Hexadecimal $3A5 3A5 

Hexadecimal $BAD1 0BAD1 

Label BAD1 BAD1 

Tatile 0-1. Numeric Notation 

Additional notations are introduced in Chapter 1. 

Special Symbols 

Four special symbols are used in this manual to emphasize information 
about helpful or unusual features of the system. 

This symbol precedes a paragraph that contains especially useful 
information. 

Watch out! This symbol precedes a paragraph that warns you to 
be careful. 

Stop! This synnbol precedes a paragraph warning you that you 
are about to destroy data or harm hardware. 

This symbol precedes a paragraph that is specific to versions 1 .1 , 
1 .2, and 1 ,3 of SOS, Note especially that, although the symbol 
indicates version 1,2, it is also applicable to versions 1 .1 and 1.3. 
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1. 1 About Operating Systems 



An operating system is the traffic controller of a computer system. A 
well-designed operating system increases the power and usefulness of a 
computer in three important ways- First, an operating system establishes 
an abstract machine that is defined by its concepts and models, rather 
than by the physical attributes of particular hardware. Second, it acts as 
a resource manager, to ease the programming task. Finally, it provides 
a common foundation for software. 



If you are an experienced programmer of small computers, 
V_-/ such as the Apple II, but you have never written large programs 
for a machine with an operating system, you should pay 
particular attention to this section, 

1.1,1 An Abstrac t Machine 

The low-level programming language of a computer is determined 
not only by its central processor, but by its operating system as well. 
The operating system is thus an essential part of the programming 
environment: Icnowing how it works lets you write programs that use 
the full power of the machine. 

Most importantly, the combination of hardware and operating system 
software creates an abstract machine that is neither the hardware nor 
the operating system, but a synthesis of both. This is the machine you 
program. 

The major advantage of the abstract-machine concept is that a program 
written for the abstract machine is not bound by the current configuration 
of the hardware. The operating system can compensate for expansions, 
enhancements, or changes in hardware, making these changes invisible 
to the programs. Thus programs properly written for an abstract machine 
need not be modified to respond to changes or improvements in the 
hardware. 



1.1.2 A Resource Manager 

An operating system also controls the flow of information into, out of. 
and within the computer It provides standard ways to store and retrieve 
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information on storage devices, communicate with and control 
input/output devices, and allocate memory to programs and data. It also 
provides certain "housekeeping" functions, such as reading and setting 
the system clock. 

The operating system saves you work. Vou don't have to write your own 
procedures for disk-access, communications, or memory-management: 
the operating system performs such functions for you. 

1.1.3 A Common Foundation for Software 

An operating system also provides a common base on which to build 
integrated applications. This, above all. promotes compatibility between 
programs and data. If two programs use the same file structure and the 
same memory-management techniques, it's much easier to make the 
programs work with each otherand share data. If all mass storage devices 
support a common file structure, it is much easier for a program to expand 
its capacity by substituting a larger devtce. 

Any service provided by SOS is provided only by SOS. The 
continued correct operation of your program under future 
versions can be assured only if you use the services provided 
and make no attempt to circumvent SOS. 

1.2 Overview of the Apple III 



The Apple Ill/SOS Abstract Machine has six principal parts 
(see Figure 1-1): 

• An interpreter, which is the program executed at boot time; 

• The operating system, SOS; 

• Memory; 

• A set of files, for the storage and transfer of information; 

• A set of devices and drivers, for the communication of 
information; and 

• The 6502 instruction set, with extended addressing capabilities. 
All of these rest on a base created by the hardware of the machine. 
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Figure 1-1, The Apple Ill/SOS Abstract Machine 
The rest of this section describes these parts in brief. 
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1.2.1 The Interpreter 

An interpreter is an assembly-language program that starts automalicalty 
when SOS boots. Interpreters include the Business BASIC and Pascal 
language interpreters, as well as the application program Apple Writer til. 

Only one Interpreter can reside in the system at a time. An interpreter 
Is loaded each time the system is booted; the system cannot operate 
without an Interpreter In addition, language interpreters such as Pascal 
and BASIC allow separate assembly-language routines, called modules. 
to be loaded and executed. 

An interpreter consists of 6502 assembly-language code, including SOS 
calls. The construction and execution of Interpreters and modules is 
described in Chapter 7, 

7.2.2 SOS 

SOS is the operating system of the Apple III. It provides a standard 
interface between the interpreter and the computer's hardware. 
An interpreter communicates with SOS by making subroutine-like 
calls to SOS, SOS returns the results of each call to the interpreter. 
SOS calls are of four types: 

• File management calls read, write, create, and delete files, 

• Device management cails read the status of a device or 
control the device. 

• Utility management calls provide access to the system clock, 
joystick, and event fence. 

• Memory management calls allocate and deallocate memory for 
the interpreter, 

SOS also controls all asynchronous operations of the computer, through 
the mechanisms of interrupts and events, as described in Chapter 6. An 
interrupt from a device is detected by SOS and handled, underthe control 
of SOS, by an interrupt handler in that device's driver An event is detected 
by a device driver and handled, under the control of SOS, by an event- 
handler subroutine In the interpreter. 
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SOS is always resident in tine system and is loaded from the boot disk's 
SOS. KERNEL and SOS, DRIVER files when the system is booted. The 
SOS. KERNEL file contains that part of the operating system that must 
always bepresentforthe Apple III to function and which does not change 
from machine to machine: fife management, memory management, utility 
management. Some device management functions, such as translating 
file calls into calls to device drivers, arealsointheSOS kernel. The Disk III 
driver is included in the SOS kernel because the Apple III system always 
has a built-in Disk III, 

The SOS,DRIVER file includes other device management functions. 
This file, which is also loaded at boot time, contains the drivers you can 
reconfigure or remove. The device dnvers provide a way for a specific 
device to support the general concept of a file. For example, you can write 
a program to send output to the driver .PRINTER . The program contains 
no information about individual printers: it merely tells SOS to print so 
many bytes on the printer represented by .PRINTER . The driver 
PRINTER translates the SOS calls into the control codes for the specific 
printer it is written for To use a different printer, you need only configure 
a different .PRINTER driver into the operating system. 

You can find more information about the standard device drivers 
that control the text and graphics displays, the keyboard, and the 
communications ports in the Apple tit Standard Device Drivers Manual; 
information about other drivers is in the manuals for their devices; 
information about creating your own device drivers is in {he Apple III 
SOS Device Driver Writer's Guide. 

1.2.3 Memory 

Although the standard addressing space of the 6502 microprocessor is 
64K bytes, the Apple III machine architecture and SOS provide efficient 
access to a maximum of 51 2K bytes of memory through the use of two 
enhanced addressing modes. These modes are described in Chapter 2, 




Current hardware supportsupto 256K bytes 
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Several SOS calls create a memory management and allocation system. 
An interpreter can cause SOS to find an unused segment of memory, and 
return that segment's size and location. SOS keeps track of all allocated 
segments, so ttiat a program that uses only SOS-allocated segments 
cannot accidentally destroy programs or data used by other parts of 
the system. 

The memory management system also allows an interpreter to acquire 
additional memory. This means that an Interpreter need not be restricted 
to the use of a specific area of memory, so that the interpreter wilf run 
without modification on machines of different memory sizes: the only 
difference will be in performance. 

SOS acts as a memory bookkeeper, keeping track of memory allocated 
to the interpreter, its modules, and the operating system. This bookkeeper 
notes whether memory allocation ever violates the rules (that is, whether 
the same memory space is ever allocated to two programs at the same 
time); but it does not halt a program that breaks the rules, so the 
programmer must exercise care. An executing program has access to 
all memory within its own module. Any time it requests additional space, 
it should release it as soon as it is not needed 

1.2.4 Files 

F/7es are the principal means of datastorage in the Apple III. A file is simply 
a standardized means by which information is organized and accessed 
on a peripheral device. All programs and data (even the operating system 
itself) are stored in files. All devices are represented as files. 

The way a file is used is independent of the way the hardware actually 
accesses that file. Files can be either on random-access devices (such as 
disk drives) or on sequential -access devices (such as communications 
interfaces); files on the Apple Ill's built-in disk drive are accessed inexactly 
the same manner as files on a large remote hard-disk drive. SOS lets you 
perform simple operations on files (such as read, write, rename) that are 
actually complex operations on the devices that store your information. 
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SOS uses a hierarchical structure of directories and subdirectories to 
expedite file access, As described in \Ue Apple III Owner's Guide, related 
files can be grouped together in directories and subdirectories, and 
special naming conventions make it easier to specify groups of fiies. 



7.2.5 Devices 

The Apple ill can support a variety of peripheral devices. Some of these 
devices are built into the Apple III itself; others must be plugged into 
peripheral interface connectors insidethe Apple III. 

SOS supports operations on two types of devices: block devices and 
character devices. Block devices read and write blocks of 51 2 bytes in 
random-access fashion; character devices read and write single bytes 
in sequential-access fashion: both support the concept of a file to which 
you read and write single bytes. SOS defines the ways in which you can 
control and read the status of both kinds of devices. 



1.2.6 The 6502 Instruction Set 

The 6502 is the processor in both the Apple II and the Apple III, but in the 
Apple III its power is extended in two ways: 

• Additional hardware gives it two enhanced addressing modes, 
allowing it to address efficiently far more than 64K bytes 

of memory. 

• The BRK instruction is used to execute SOS calls. SOS calls can 
be thought of as an extension of the 6502 instruction set: that 

is, a set of 4-byte 6502 instructions that are emulated in software 
by the operating system 
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This chapter describes the methods an interpreter uses to obtain and 
manipulate memory. The actual writing and construction of an interpreter 
is described in Chapter 7. 

2. 1 Addressing Modes 



Since the 6502'3 address bus is only 16 bits wide, it can directly address 
only 64K bytes. This is not enough memory for many of the applications 
the Apple III is intended for, so the Apple Ill/SOS system has been 
designed with new addressing techniques to allow you to efficiently 
access up to 51 2K bytes of memory. 

The Apple Ill's memory is subdivided into banks of 32K bytes each. The 
architecture of SOS can support up to 16 such PanKs, or a system with 
51 2K bytes. 

The current Apple III hardware supports up to eight banks, or 
256K bytes. 

Certain regions of memory are reserved for use by SOS and its device 
drivers; the rest is available for use by an interpreter and its data. 

Two methods are used to specify locations in the Apple Ill's memory: 

• bank-switched addressing, which specifies locations with a 
bank-plus-address form; and 

• enhanced indirect addressing, which specifies locations with 
a three-byte pointer form. 

2.1.1 Ban k-Switched Memory A ddressing 

The bank-switched method is the standard memory-addressing technique 
used to execute interpreter code; it can also be used for data access. In 
bank-switched addressing (see Figure 2-1 ), the 6502's addressing space 
is filled by two banks at a time. 
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Figure 2-1. Bank-Switched Memory Addressing 

One bank (called the "SOS bank", or S-bank) is always present. This 
unswitched bank occupies locations $0000 through $1FFF and locations 
$A000 through $FFFF in the standard 6502 addressing space. The larger 
region contains SOS. The smaller region contains data areas used by 
SOS, as well as the interpreter's zero page and stack page, described in 
section 2.2.1. 

Locations $2000 through $9FFFare occupied by one of up to 15 
switchable banks, numbered $0 through $E. Normally, the highest bank in 
the system (bank $2 for a 128K system, bank $6 fora256K system, bank 
$E for a 51 2K system) is switched into this space: this bank contains the 
interpreter. But the interpreter can cause any of the other banks to be 
switched in, either to execute code or to access data. To switch another 
bank into the address space (see Figure 2-2), the interpreter changes the 
contents of the bank register (memory location $FFEF), as explained in 
section 2.4.1. 
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Figure 2-2. Switching in Another Bank 

Locations within the S-bank or the currently selected bank may be 
specified by a two-byte address, notated here as four hexadecimal digits: 

$nnnn $0000 to $1 FFF S-Bank Address 

$2000 to $9FFF Current-Bank Address 

$A000 to $FFFF S-Bank Address 

where each n is a hexadecimal digit. This address uniquely identifies 
any location within the current address space. 

Locations in bank-switched memory (all banks but the S-bank) are 
specified by their four-digit address, plus the number of the bank they 
reside in. The addresses of these locations are in the form: 

$b:nnnn $0:2000 to $0:9FFF Bank-Switched 
$1:2000 to $1 :9FFF Addresses 

$E:2000 to $E:9FFF 
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where $b is a hexadecimal digit from $0 to $E, and each n is a 
hexadecimal digit. 

Addresses in the current bank can be specified with or without 
the bank number: that is, in current-bank form or in bank- 
switched form. The addresses $E:2000 and $2000 are equivalent 
if bank $E is switched in. 

Note that bank-switched address specifications such as $0:FFDF and 
$2:01 FF are not standard: these addresses, being in S-bank space and 
unaffected by bank-switching, are normally specified without the bank 
number. 

Address Specifies 



$0:2000 First location in bank 

$2:9FFF Last location In bank 2 

$F:32A4 Invalid: there is no bank $F. 

$1 :B700 Non-standard: use S-bank specification $B700 

Table 2-1. Addresses in Bank-Switched Notation 




2.1.2 Enhanced Indirect Addressing 

The second memory-addressing method, enhanced indirect addressing, 
uses a three-byte extended address to access each memory location. 
This method lets a program in one bank access data in other banks. 
Enhanced indirect addressing lets any 6502 instruction that allows 
indirect (-X or-Y) addressing to access data within any pairoi adjacent 
memory banks. (For example, banks $0 and $1 , and banks $1 and $2, 
constitute bank pairs.) This addressing method is considerably more 
efficient than bank-switching, since the bank register need not be altered 
in order to access data in other banks. 

Enhanced indirect addressing is used for data access only 
Programs cannot execute in the memory space defined by this 
method. 
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An extended address specification consists of a two-byte address and 
one extension byte, or X-byte, which has no relation to the 6502's X 
register- The address is in standard 6502 form (low byte followed by 
high byte), and may be from $0000 to$FFFF, with some restrictions 
explainsd later. The X-byte is of the form shown in Figure 2-3. 



unused 

J L 



Figure 2-3. X-byte Format 



Bit 7 of the X-byte is the enhanced-addressing bit. or E-bit\ bits through 
3 are the bank-pair field, or B field. If the E-bitis0, normal indirect address- 
ing takes place, using the S-bank and current bank, ff the E-bit is 1, 
enhanced indirect addressing (see Figure 2-4) takes place, and the B field 
determines which of several bank pairs are mapped into the address space. 
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Figure 2-4. Enhanced Indirect Addressing 



The X-byte selects one of up to 16 pairs of banks to fill the64K memory 
space, and the two-byte address selects a specific location within the 
bank pair. Extended addresses have this form: 




$8)<:nnnn 



$80:0100 to $80:FFFF 
$81:0100 to $81:FFFF 



Banks and 1 
Banks 1 and 2 



$8m:0100 to $8m:7FFF 
$8F:0000 to $8F:FFFF 



Bank m 

S-bank and Bank0 



where x and each n are hexadecimal digits, and m is the number of the 
highest switchable bank. 

Extended address notation differs from bank-switched address notation 
in the number of digits before the colon. An extended address begins 
with a two-digit X-byte, whose first digit is always $8; a bank-switched 
address begins with a one-digit bank number. 

The X-byte can range from $80 (banks and 1) to $8m (bank m). where 
m is the number of the highest bank: $2 for a 1 28K system; $6 for a 256K 
system; or $E for a 51 2K system. The highest bank pair is not really a pair: 
it ends at $8m:7FFF and higher addresses will produce undefined results 
The X-byte has a singular value, $8F, which pairs the S-bank with bank $0 
(see hand paragraph below). 

KJ«^ Note that the addresses $8n:0000 to $8n:0CIFF are not accessible 

v y via enhanced indirect addressing Any reference to these 

addresses will give you a location on the currently selected zero 
page. To address these locations {$8n:0000 to $8n:00FF) you 
can use the equivalent address in the next-lower bank pair; that 
is. $a(n-1):8000 to $B{n-1);80FF. (See fourth example below). 
This trick does not work for the addresses $80:0000 to $80:00FF: 
for these addresses, you can use the equivalent addresses 
$8F:2(J00 to $8F:20FF (see hand, below). 

In addition, the addresses $8n;FF00 through $8n:FFFF should generally 
be avoided, as indexing these addresses by the value in the Y-register 
may cause a carry and produce an address in the range $8n:0000 
through $8n:00FF— this address is on the zero page. The locations 
$8n:FF00 through $8n:FFFF may be addressed with the equivalent 
addresses in the next-higher bank pair: that is, $8(n+1):7F00 through 
$8(n+1):7FFF 
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The invalid and risky regions are sliown in color in Figure 2-4. 
Address Specifies 



$80:8000 First location in bank $1 

$81;7FFF Last location in bank $1 

$03:2215 Not an extended address: X-byte ignored 

$81 :002E Invalid: use $80:802E 

$81:FF2E Risky: use$82:7F2E 



The X-byte S8F is unique: it caus^ the S-bank and bank $0 to be 
switched into ttie 6502's address space in their standard bank- 
switched arrangement. Bank $0 is mapped to the locations 
$6F:2000 to $8F:9FFF so no part of il conflicts with the zero 
page. The X-byte S8F is used pnmahly by graphics device drivers 
to access the graphics area at the bottom of bank $0, (See the 
eye paragraph in section 2,4,2.2.) 



An Apple III program's execuiion environment defines the state of the 
machine while that program is running. The two major programs, SOS 
and your interpreter, run in different environments; assembly-language 
modules run in an environment much like the interpreter environment; 
and device drivers run in part of the SOS environment. 

The environment defines the location of the program being executed, 
the location and type of memory that program can access, the processor 
speed, and the kinds of interrupts the program can handle. (Interrupts are 
explained in Chapter 6 and in the >App/e /// SOS Device Driver Writer's 
Guide.) The environment also determines whether and how one program 
can communicate with another The environment also specifies which 
zero page and stack the executing program will use, as explained in the 
next section. 



Table 2-2. Extended Addresses 




2.2 



Execution Environments 
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2. 2. 1 Zero Page and Stack 



The 6502 microprocessor reserves the first two pages in memory for 
special access. The zero page (locations S0000 through $00FF> is used 
by several 6502 addressing modes for indirect addressing and to save 
execution time and code space. 

But the zero page has only 256 locations, and if both the interpreter and 
SOS are trying to save data in that page, it quickly fills up. The Apple III 
resolves this contention by allocating separate zero pages to the 
interpreter ($1 A00 through $1 AFF) and SOS ($1800 through $18FF). 
Thus when an interpreter accesses a zero-page location (by executing 
an instruction followed by a one-byte address), it's accessing an area 
Of memory completely separate from the zero-page storage of SOS. 

Similarly, page one {locations $0100 through $01 FF) is used as a 256- 
byte push -down stack for temporary data storage and subroutine and 
interrupt control. Programs that call many nested subroutines and save 
many temporary values on the stack can quickly fill it up. Again, the 
Apple III resolves this contention by allocating separate stacks to the 
interpreter ($1 B00 through $1 BFF) and to SOS {$0100 through $01 FF). 

Each zero page and stack is accessible from other environments as a 
different page in memory. The SOS kernel, for example, can access 
locations in the interpreter's zero page by using the addresses $1 A00 
through $1AFR 




An interpreter should access only Its own zero page and stack. 
An interpreter that writes into the SOS zero page or stack will 
generally come to an untimely and untidy end. 
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2.2.2 The Interpreter Environment 

The interpreter is in tine higlnest switciiable bank of memory {bank $n): 
for a 128K system, this would be bank $2; for a256K system, bank $6; 
for a 51 2K system, bank $E. Figure 2-5 shows the interpreter placement 
in memory. 



Interpreter 



$0000 
\ $2000 

. last 
bank 

SA00a 
SB800 

SFFFF 



Figure 2-5. Interpreter Memory Placement 

An interpreter shorter than 6K bytes is located entirely in 
locations SA000 through $B7FF of the S-bank. An interpreter 
longer than 6K ($1800) bytes begins in the highest bank (the 
first byte is between $n:$2000 and $n:$9FFF), and ends in the 
S-bank (the last byte is at location $B7FF). For example, an 
interpreter that is 10K (S2800) bytes long in a 128K system would 
reside from $2:9400 to SB7FF. 

Although the maximum size of an interpreter is 38K ($9800) bytes, we 
recommend that interpreters be restricted to 32K ($8000) bytes, for 
compatibility with future versions of SOS. A longer interpreter can be 
split up into a main unit and one or more separately-loaded modules. 
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An interpreter runs at a nominal 2 MHz clock rate. In practice, execution 
speed is approximately 1.4 MHz if the Apple Ill's video display is on; 
turning off the video display (using the .CONSOLE driver's CTRL-5 
command) raises execution speed to 1 .8 MHz. (The remaining 0.2 MHz is 
consumed by memory refresh.) An interpreter must be fully interruptable. 
so no timing loop In an interpreter m\\ be reliable, except to provide a 
guaranteed minimum time. 

The interpreter's zero and stack pages, always accessible by normal 
zero-page and stack operations, can also be addressed as pages $1 A and 
$1B. Page $16 is used as the extension page for enhanced indirect 
addressing (see section 2,1 .2). 



Environment Attribute Setting 




IRQ Interrupts Enabled 

NMI Interrupts Enabled or Disabled 

Processor Speed Full speed 

Zero Page Page $1 A 

Stack Page Page$1B 

Extend Page Page $16 

Bank Highest 

Table 2-3. Interpreter Environment 

Of the above environment attributes, only the bank register 
(location $FFEF) should be changed by an interpreter 
Adherence to this rule is essential forcorrect system operation. 



An assembly-language module operates in the same environment as the 
interpreter, except that it may reside in a different bank (see section 7,4), 
An assembly-language module must share the interpreter's zero page 
and stack. 



2.2.3 SOS Kernel Environment 

The SOS kernel (SOS without its device drivers) resides in the upper 
regions of S-bank memory, and uses the lower areas of the S-bank for 
data and buffer storage (see Figure 2-6). 
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Figure 2-6. SOS Kernel Memory Placement 

The SOS kernel uses no bank-switched memory. 

SOS uses its own zero page and stack {pages $18 and $01, respectively). 
It can be interrupted by both IRQ and NMI interrupts. 

Environment Attribute Setting 



IRQ Interrupts 
NMI Interrupts 
Processor Speed 
Zero Page 
Stack Page 
Extend Page 
Bank 



Enabled 
Enabled 
Full speed 
Page $18 
Page $01 
Page $14 
S-bank 



Table 2-4. SOS Kernel Environment 



2,2.4 SOS Device D river E n vironmen t 

Device drivers are placed directly below ttie interpreter (that is, in memory 
locations with smaller addresses), in the highest-numbered bank in the 
system (see Figure 2-7). Any drivers that do not fit into that bank are 
placed in the next lower bank, beginning at $9FFF and moving down to 
lower-numbered addresses. 



Programs and Meniory 21 



driver 



driver 



SOS kernel 



dnvei 



interpreter 



SOS Iterne! 



$20M 

. lasi 
bank 

$A000 
$B800 

SFFFF 



Figure 2-7, SOS Device Driver Memory Placement 

Drivers share the SOS zero page and stack. A driver must reserve space 
within itself for ail buffers that it uses: it cannot claim any memory outside 
itself. 



Environment Attribute Setting 



IRQ interrupts 
NMI Interrupts 
Processor Speed 
Zero Page 
Stack Page 
Extend Page 
Bank 



Enabled or Disabied 

Enabled or Disabied 

Full Speed or Fixed 1 IVIHZ 

Page $18 

Page $01 

Page $14 

Interpreter's or Lower 



Table 2-5. SOS Device Driver Environment 



A device driver can alter the execution speed; it can disabie interrupts for 
up to 500 microseconds to run timing loops: for more information, see the 
Apple III SOS Device Driver Writer's Guide. 
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2. 2.5 En vironmen t Summary 

The environment determines what actions a program can perform and 
what other programs it can communicate with. The following table 
summarizes the capabilities of each environment. 

Function Interpreter' Kernel Driver 



Can perfornn a SOS call 


Yes 


No 


No 


Can call SOS subroutines 


No 


Yes 


Yes 


Can be interrupted 


Yes 


Yes 


Yes*' 


Can respond to IRQ 


% 


Yes 


Yes 


Can respond to NMI 




Yes 


No 


Can disable interrupts 


No 


Yes 


Yes 


Can detect and queue an event 


No 


Yes 


Yes 


Can respond to an event'" 


Yes 


No 


No 


Can access interpreter memory 


Yes 


Yes 


Yes 


Can access free memory 


Yes 


Yes 


Yes 



■ An assembly-language module runs in the same environment as its interpreter, 

A device driver can contain a special section, called an interrupt handler, designed 
specilically to handle IRQ interrupts. 

Events, or software interrupts, are defined in Chapter s. 

Table 2-6. Environment Summary 
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2.3 Segment Address Notation 



When an interpreter is loaded into memory, it occupies part of the S-bank 
and part of the highest-numbered bank. The region below the interpreter 
is occupied by the device drivers; the region below the drivers is free 
memory, as shown in Figure 2-8. 
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Figure 2-8. Free Memory 

The interpreter has access to its own space If it needs more memory, it 
can gain access to free memory by using the SOS memory calls. These 
calls use segment address notation, to define segments of memory for 
allocation (see Figure 2-9). Segment address notation resembles bank- 
switched address notation, except that it defines addresses of segments, 
not bytes, of memory in either the S-bank or a switchable bank. A page is 
a group of 256 contiguous bytes with a common high address byte. A 
segment is a set of contiguous pages. The lowest page in a segment is 
called the base; the highest page is called the limit. Each bank of memory 
contains 128 pages, numbered $20 through $9F 
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Figure 2-9. Segment Address Notation 

Each page of memory has a corresponding segment address, which is 
very similar to that page's starting address in banl<-switched memory, 
The format is: 

$bb:pp $00:20 to $00:9F Segment 

$01:20 to $0t:9F Addresses 



$0E:20 to $0E:9F 

where bb is the bank number (one byte) and pp is the page number 
(one byte) in that bank. Notice that for segment addresses in bank- 
switched memory the page part of the segment address is always between 
$20 and $9F. 

Segment Address Specifies 



$01 :30 Page beginning at $01 :3000 

$04:62 Page beginning at $04:6200 

$00;9F Page beginning at $00:9F00 

Table 2-7. Addresses In Segment Notation 

A segment address specifies an entire page, not just the first 
location in that page. A base segment address and a limit 
segment address together specify a segment. 
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Segment addresses can also specify pages in S-bank memory: the format 
then is slightly different. For segments in the lower part of the S-bank, 
the bank part of the segment address is always $0F, for segment addresses 
in the upper part of the S-bank, the bank part of the segment address is 
always $10. In either case, the page part (as above) is the same as the 
high byte of the memory address. 

$bb:pp $0F:00 to $0F:1 F Segment 

$10:A0 to $10:FF Addresses 

Segment Address Specifies 



$0R14 Page beginning at $1400 

$0F;02 Page beginning at $0200 

$10:B8 Page beginning at $B800 

Table 2-8. Addresses in Segment Notation, S-Bank 

Before segment addresses can be used by an interpreter, they must be 
converted into bank-switched or extended addresses. These conversions 
are explained in section 2.4.3. The SOS memory calls that use segment 
addresses are explained below. 



2.3. 1 Memory Calls 

Interpreters use these SOS calls to allocate and release memory. 
The name of each call below is followed by its parameters [in boldface). 
The input parameters are directly-passed values. The output parameters 
are all directiy-passed results. The SOS call mechanism is explained 
in Chapter 8; the individual calls are described fully in Chapter 1 1 of 
Volume 2 

REQUEST_SEG 

[base, limit, seg id. value; seg num: result] 

This call requests the allocation of the contiguous region of memory 
bounded by the base and limit segment addresses. A new segment is 
allocated if and only if no other segment currently occupies any part of 
the requested region of memory. If a segment is allocated, an entry for 
it is made in the segment table. 
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F[ND_SEG 

[search mode, segjd, pages: value, pages, base, limit, seg num: result] 

This call searches memory from the highest memory address down, until 
the first free space of length pages that meets the search restrictions in 
search_mode is found. If such a space is found, this free space is allocated 
to the caller as a segment (as in REQUEST_SEG): both the segment 
number and the location in memory of the segment are returned, If a 
segment with the specified size is not found, then the size of the largest 
free segment which meets the given criterion will be returned in pages. In 
this case, however, error SEGRQDN will be returned, indicating that the 
segment was not created. 

CHANGE_SEG 

[seg nutn, change mode, pages: value; pages: result] 

This call changes either the base or limit segment address of the specified 
segment by adding or releasing the number of pages specified by the 
pages parameter If the requested boundary change overlaps an adjacent 
segment or the end of the memory, then the change request is denied, 
error SEGRQDN is returned, and the maximum allowable page count is 
returned in the pages parameter 

GET_SEG_INFO 

[seg num: value; base, limit, pages, segJd; result] 

This call returns the beginning and ending locations, size in pages, and 
identification code of the segment specified by seg_num. 

GET_SEG_NUM 

[seg address; value; seg num: result] 

This call returns the segment number of the segment, if any, that 
contains the segment address. 
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RELEASE_SEG 
[segnum: value] 

This call releases the memory occupied by segment seg^num by 
removing the segment from the segment table. The memory space 
formerly occupied by segment seg_num can now be allocated to another 
program. If seg num equals zero, then all non-system segments (those 
with segment identification codes greater than S0F) will be released. 

2.4 Memory Access Techniques 



The Apple III augments the eleven addressing modes of the 6502 in two 
ways: bank-switching and enhanced indirect addressing. Bank-switched 
addressing is used for executing code segments residing in bank- 
switched memory. Enhanced indirect addressing is used for access to 
data in memory. These techniques give your programs efficient access 
to all of memory. 

In addition, SOS uses segment address notation to allocate free memory 
for programs. Segment address notation is reserved for the SOS memory 
management calls, which the interpreter uses to obtain and release 
memory. 

This section discusses the most common modes of access to program 
and data storage areas in the Apple III. It shows how the memory 
addressing methods introduced in section 2.1 and 2.3 are used in 
performing various operations, and how these methods can be used 
in a program. It also presents sample algorithms that convert the address 
of a location from one form to another. 

2.4. 1 Subroutine and Module Addressing 

The 6502"s JMP and JSR instructions affect the flow of control within 
an Interpreter As the interpreter resides in theS-bank and the highest 
switchable bank, the destination for these instructions is specified in 
S-bank or current-bank notation The JSR and JMP instructions should 
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be used in the normal 6502 absolute addressing mode Here are three 
examples of such instructions, 

AA40I 4C 3A85 JMP 853A ; Jump to location $853 A 

; in interpreter 

8B801 20 5022 JSR 2250 ; Jump to subroutine at 

; location $2250 

23BB|4C52B6 JMP 0B652 ; Jump to location $B652, 

; in the S-bank 

All assembly-language listings in this manuat were made wfth 
the Apple III Pascal Assembler This is the only assembler 
supported for the Apple III. 

If an interpreter wishes to transfer control to a module residing in another 
bank, the normal addressing mode will not work: the interpreter must 
switch in the proper bank before performing the JMP or JSR. 

Bank-switching can be performed only by code residing in 
S-bank (that is, unswitched) memory. An interpreter tinat 
performs bank-switching should use a single dispatching 
routine, located between locations $A000 and $B7FF in the 
S-bank, for all bank-switching. 

The interpreter switches in a given bank by storing the number of the bank 
in the bank register (location $FFEF). Once this is done, the JIVIP or JSR 
instruction can be executed normally. Here's a valid jump: 



00001 FFEF 

A05OI A901 
A052I 8D EFFF 
A055I 40 6B32 



BREG 



.EQU 0FFEF 



LDA 
STA 
JMP 



#01 

BREG 

326B 



; Define bank register 

; Jump to location $1 :326B 



Here's a jump into oblivion: 



00001 FFEF 

8B40I A902 
8B42I 8D EFFF 
8B45I 40 4440 



BREG .EQU 0FFEF ; Define bank register 

LDA #00 ;Thts program wit! crash, 

STA BREG ; as it is not located 

JMP 4044 ; in the S-bank. 
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The module, onceswitched-in, can use current-bank addresses to 
jump around inside itself, and can JIVIP or RTS back to the part of the 
interpreter in S-bank memory, without bank-switching. The interpreter 
must, however, switch the highest bank back in before any interpreter 
code below S-bank memory can be executed. To do this the interpreter 
must save its own bank number before calling the module. The interpreter 
can read the contents of the bank register to find the number of its bank, 
then call a module and, upon returning, restore the proper bank. The 
following subroutine demonstrates how an interpreter would call a 
module located at $1 :3300- 



00001 FFEF BR EG 


EQU 


0FFEF 


; Define bank register 


A700I ADEFFF 


LDA 


BREG 


; Get the current bank 


A703I 48 


PHA 




; Save it on the stack 


A704I A901 


LDA 


#01 


; Switch in 


A706I 8DEFFF 


STA 


BREG 


: bank $1 


A709I 20 0033 


JSR 


3300 


; Call the module 


A70CI 68 


PLA 




; Upon return, restore 


A70DI 8D EFFF 


STA 


BREG 


; the bank number. 


A710I 60 


RTS 




; Return to main code 




Only the lower four bits of the bank register contain the current bank 
number; tlie upper four bits should be zero. 



2A.2 Data Access 

An interpreter can access data in three places: 

• In the interpreter's zero page; 

• In a table within the interpreter itself; 

• In a segment allocated from free memory. 

Data can be accessed in locations $0000 through $0aFF, the interpreter's 
zero page, by instructions in absolute, zero-page, or zero-page indexed 
mode. For example, 



6BA7I A5 54 LDA 54 ; Value on zero page 

747FI8DE300 STA 00E3 ; Also on zero page 
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To access data in a table within itself, the interpreter must use the 
absolute address of the table (in current-bank orS-bank notation) In 
absolute or indexed addressing mode, 

70751 CD 9BAB CMP 0AB9B : Compare location $AB9B 

; to accumulator 

58501 BD 5022 LDA 2250,X ; Load accumulator from 

; byte $2250 + X 

Data in free memory can be accessed by an interpreter in two ways: by 
bank-switching or by enhanced indirect addressing. All data used by an 
interpreter must be stored in SOS-allocated segments (see section 11.1 of 
Volume 2). To begin storing data in free memory, an interpreter must first 

requestasegmentof free memory from SOS, using a REQUEST SEG or 

FIND_SEG call. SOS wil! return a segment address, which the interpreter 
can change into an address more suitable for data access. Conversion 
algorithms are described in section 2.4.3, 



2.4.2. 1 Bank-Switched Addressing 

Bank-switching for data access operates just like bank-switching for 
module execution (described in section 2.4.1). To perform an operation 
on location $b:nnnn, store $b in the bank register and perform the 
operation on absolute location $nnnn. For instance, 



00001 FFEF 


BREG. 


.EQU 


0FFEF 


; Define bank register 


00001 




ORG 


0A3AA 


; Code starts here 


A3AAI AD EFFF 




LDA 


BREG 


; Save current bank register 


A3ADI 48 




PHA 






A3AEI A000 




LDY 


#00 


; Perform a loop to 


A3B0I 8C EFFF 




STY 


BREG 


; zero all locations 


A3B3I 98 




TYA 




; from $0:9800 to 


A3B4I 990098 


LOOP 


STA 


9800, Y 


; $0:98FF. 


A3B71 08 




INY 




P 


A3S8I 00 FB 




BNE 


LOOP 




A3BAI 68 




PLA 




: Store bank register 


A3BBI8D EFFF 




STA 


BREG 


1 
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Just as in module execution, the code to perform bank-switched data 
access must reside in the part of the interpreter that is located in S-bank 
memory, and you must remember to restore the original contents of the 
bank register before returning to the main part of the interpreter 

2.4.2.2 Enhanced Indirect Addressing 

Enhanced indirect addressing allows an interpreter to access any location 
in bank-switched memory without having to switch in the proper bank 
and then switch back. Any 6502 instruction that supports indirect-X or 
indirect-Y addressing (ADC. AND, CMP, EOR, LDA, ORA, SBC, STA) can 
use enhanced indirect addressing. 

To perform a normal (not enhanced) indirect operation on location 
$hilo, you store $/o in a location $nn on zero page, and store $hi in the 
foilowing location. You must also store $00 in location $nn-i-l of the 
X-page: the $00 turns off extended addressing. Then you perform the 
operation in an indirect mode on location $nn. The two bytes at $nn 
are a pointer: you can increment, decrement, and test them to move the 
pointer through your data structure. 

Enhanced indirect addressing merely adds one step to this process, To 
perform an enhanced indirect addressing operation, in the interpreter 
environment, on location $xx:liilo, you store $/o in $nn, $hi in $nn+1 , 
and $xx in location $76nn+1 . Then perform the operation in an indirect 
mode on location $nn. The location $16nnT^ is the extension byte, or 
X-byte, of the pointer 

Enhanced indirect addressing takes effect whenever you execute an 
indirect-mode instruction and bit 7 of the pointer's extension byte(X-byte) 
is 1 : that is, whenever the extension byte is between $80 and $8F. If you 
wish to perform normal indirect operations, using bank-switched 
addressing rather than enhanced indirect addressing, you shouid store 
your pointer in bank-switched form in the zero page, and set its extension 
byte to $00, which will make sure bit 7 is 0. For instance, 
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61EE| A989 


LDA 


#89 


; Perform a LDA $82:3289 


R1 Pffl 1 Ac; c;7 
D 1 rVJ \ oO D/ 




3/ 


1 To set up, first put 


61F2I A9 32 


LDA 


#32 


; $lohi in zero page 


61F4I 85 58 


STA 


58 


; locations $57 and $58; 


61F6I A9 82 


LDA 


#82 


: then put $xx into 


61F8I 8D 5816 


STA 


1658 


; location $1658. 


61 FBI A0 00 


LDY 


#00 


; Index by0. 


61FD| B1 57 


LDA 


(57),Y 


; Perform the operation. 



Once the three bytes are stored, you can manipulate them almost as 
easily as a two-byte pointer, and you can use one pointer to access data 
in all 1 5 switch able banks (a total of 480K). This makes it easy to handle 
large data structures. 

Remember that enhanced Indirect addressing is different frorri 
bank-switched addressing. For a description of the two 
methods, see section 2.1 . 

If you are using the enhanced indirect-Y addressing mode and 
are using the Y-register to index from an extended address, we 
strongly recommend that you avoid using addresses $8n:FF00 
through $8n:FFFF. Adding a Y value to one of these addresses 
may cause a carry and create an address in the range S8n:0000 
through $8n:00FF, which will access a location on the zero 
page. H you keep your pointer below $8n:FF00 whenever you 
are using a non-zero Y register in the enhanced indirect-Y 
addressing mode, you will avoid this problem 




2.4.3 Address Conversion 

Most interpreters deal mainly with addresses in segment and extended 
form: bank-switched addresses are used only when an interpreter must 
execute code in a different bank. But ban(<-s witched addresses are a 
convenient intermediate form between segment and extended addresses; 
they can be readily converted to either of the other forms. 

The following algorithms describe the basic conversions between 
addresses in segment, bank-switched, and extended forms. 
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2.4.3. 1 Segment to Bank-Switched 

A segment address specifies a page in bank-switched memory. 
When you convert a segment address to a bank-switched 
address, the result is the address of the first byte in that page. 

To convert a segment address $bb:pp to a bank-switched address 
^B.NNNN, 

if (bb = 0F)or(bb = 10) 

then B:=0 

else B ~ bb; 
NNNN := pp00 

For example, the following segment and bank-switched 
addresses are equivaient. 

Segment Bank-Switched 

$04:63 - $(4): (6300) = $4:6300 
$07:89 = $(7):<8900) = $7:8900 
$10:1 F = $(0):(1F00) = $0:1 F00 

The bank part, bb, of the segment address is converted to $0 if it indicates 
the S-bank, or truncated if it indicates any other bank. It then becomes 
the bank part of the bank-switched result. The page part, pp, of the 
segment address becomes the high part of the bank-switched address, 
and the low part is set to $00 

2.4.3.2 Segment to Extended 

When converting to extended form, you must be careful to make 
sure that the result is in the valid range of extended addresses. You 
must aiso handle the special cases of S-bank segment addresses 
and the segment address $00:20. 
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To convert a segment address $bb:pp into an extended address 
$XX:NNNN, 



if { (bb = $00) [zero bank] 

or(bb = $0F) (lowS-bank) 
or(bb = $10) ) JhighS-bankj 
then 
begin 
XX :=$8F ; 
NNNN pp00 
end 

else {general case) 

begin 

XX :-$80+bb-1 ; 
NNNN := pp00+$6000 
end; 



For example, the following segment and extended addresses are 
equivalent: 



Segment Extended 



$09:2A = $(80+9-1); (2A00+6000) = $88:8A00 
$02:94 = $(80+2-1); (9400+6000) = $81:FF00 
$0F:1E = $(8F):(1E00) = $8F:1E00 

iKflle segment address specifies a page in S-bank memory, the 6b part is 
ignored, and the pp part is converted to the address of the beginning of a 
page in theS-banl</bank pair of the enhanced indirect addressing space. 

If the segment address is in bank-switched memory, the bb part is 
converted to the xx byte that selects a bank pair with the specified bank 
in the top half of the pair. The pp part is then converted to the address of 
the beginning of the proper page in that bank pair 



2.4.3.3 Extended to Bank-Switched 



When changing an extended address to bank-switched form, you must 
handle the special case of an S-bank extended address. You must also 
determine whether the extended address points to a location within the 
upper or lower bank in its bank pair 
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To convert an extended address $xx :nnnn to a bank-switched 
address $B:NNNN, 



if (XX = $8F) then 
begin 
B := $0 ; 
NNNN := nnnn 
end 
else 

if (nnnn < $6000) then 
begin 

B ■- xx-$80 ; 
NNNN :=nnnn+$2000 
end 

else 
begin 

B := XX- $80+1 ; 

NNNN := nnnn-$6000 
end; 



For example, the following extended and bank-switched addresses 
are equivalent; 

Extended Bank-switched 



$86:4365 - $(86-80): (4365+2000 = $6:6365 
$82:EFB4 = ${82-7F):(EFB4-6000) = $3:8FB4 
$8F;2000 = $($0):(2000) - $0:2000 

If the extended address refers to a location in the S-bank, the bank part of 
the bank-switched address is set to $0 and the address part is used 
directly. 

If the extended address refers to bank-switched memory, then the xx part 
specifies a bank pair If the address part is less than $8000, the extended 
address refers to a iocation in the lower bank in the pair; otherwise, it 
refers to a location in the upper bank. The bank part is set to the bank 
number, and the address part is adjusted to the proper location within 
the specified bank. 
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2. 4. 4 Poin ter Manipula tion 

Most data structures you use are accessed by three- byte pointers in 
extended-address form. The preceding section described how to create 
an extended-address pointer from a segment address; tfiis section 
describes how to increment and test such a pointer. 

These algorithms are designed foreaseof explanation, not for efficiency. 
They worl<, but are not intended to be incorporated verbatim into real 
applications- 




2. 4. 4. 1 Incrementing a Poin ter 

An increment operation defines successive values of a pointer, and thus 
traces a path throughi successive locations in memory (see Figure 2-10). 
This path covers all switchable banks, but omits the S-bank. The path 
traced by the algorithm below begins at the first location in bank 0. 
extended address S8F;2000. It continues through the first page in this 
bank, then proceeds to the second page in the same bank with the 
extended address $80:0100. This path is chosen to avoid the invalid 
address range $80:0000 to $80:00FF. 







S2000 




S2FFF 




$A00a 




SFI=FF 





S0000 
S0100 



$7F00 
58000 



SFEFF 
$FFFF 



50000 

$0100 



S7F00 



SFEFF 

SFFFF 



S0000 
S0109 



$7F0a 

$B000 



SFEFF 
SFFFF 



X-byte = S8F 



X-byte = $80 



X-byte ^ Sai 



X-byte - $SD 



Figure 2-10. Increment Path 



The path then continues through the last location In bank 1 , extended 
address $a0:FFFF. The path switches to the next bank pair and continues 
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with the first location in bank 2, $81:8000. The path continues in this 
manner to the last location in the last bank in memory, at which point 
it terminates. 

The following algorithm increments an extended address $xx:nnnn. 



repeat 

nnnn nnnn +1 ; 

jf (XX = $8F) and (nnnn > $20FF) 
then begin 

XX •- $80 ; 

nnnn := nnnn-$2000 
end; 

if ( nnnn >$FEFF) 
then begin 
nnnn :-nnnn-$8000 ; 
XX := XX + 1 
end; 
until XX > $8D; 



{Move to next location. ) 

{ If bey nd I ocatio n $8 F:2 1 00 , I 

[move to location $80:0100 } 

[If near end of a bank pair, ) 

[switch to middle | 

[of next bank pair. ] 

f If no next pair, then stop. ) 



Notice how this algorithm switches from one bank to the next when 
its address part reaches $FF00. This is to prevent the pointer from 
ever taking a value between $an:FF00 and $8n:FFFF, which can 
cause problems when used in an instruction in the indirect-Y 
addressing mode. 

2.4.4.2 Comparing Two Pointers 

Two pointers can be considered equal under three conditions. When 
you compare two pointers for equality, you must test all three 
conditions. 

You can reduce the number of tests by comparing the two extension 
bytes first, then ordering the two numbers according to their 
extension bytes if they are unequal. 

The following algorithm compares $xx:nnr^n to $XX:NNNN for 
equality, assuming thatxx <=XX. 
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if ( ( {xx = XX > and (nnnn = NNNN ) ) {1] 

or ( (XX = XX-1} and (XX o$8F) and (nnnn = NNNN + $8000) ) {2} 
or ( (XX = $00 } and (XX = $8F) and (nnnn - NNNN - $2000) ) ) [3} 

then equal : = true 

The three conditions are as follows: 

i 1 i The two pointers are expressed identically; 

{2} The two pointers are expressed in terms of adjacent bank pairs: 

{3} The first pointer is expressed in bank-switched form, and the second 
is expressed in extended form. 

Note that without the preliminary sorting of the two pointers according 
to their extension bytes, two more cases (a total of 8 more byte 
comparisons) are necessar/ to test for equality. 



2.4.5 Summary of Address Storage 

Addresses in the three forms given above are stored in memory in 
these ways: 

• S-bank and current bank addresses are stored in normal 6602 
style: as two consecutive bytes, low byte followed by high byte. 
Heed the warnings on bank-switched addressing given in section 
2.4.1. 

• Segment addresses point to pages and are stored as two 
consecutive bytes, bank part followed by page part. 

• Extended addresses are stored in the zero page and X-page. The 
address is stored in the zero page as two consecutive bytes, low 
byte followed by high byte. The X-byte is stored in the X-page 
(page $0F:16, in the interpreter environment) at the byte position 
parallel to the high byte of the address in zero page. An extended 
address is referred to by the location of the tow byte of the 
address part: for instance, the pointer at location $0050 has its 
low part at S0050. high part at $0051, and X-byte at $1651 ( in 
the interpreter environment). 
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3. 1 Devices and Drivers 



A device is a part of the Apple (II, or a piece of external equipment, that 
can transfer information into or out of the Apple III. Devices include the 
keyboard and screen, disk drives, and printers. 

Devices provide the foundation upon which the SOS fite system is 
constructed. In general, your program will talk to devices only through 
the SOS file system. 

3.1.1 Block and Character Devices 

SOS recognizes two kinds of devices; character devices and block 
devices. A character device reads or writes a stream of characters, one 
character at a time: it can neither skip characters nor go back to a 
previous character A character device is usually used to get information 
to and from the outside world: it can be an input device, an output device, 
or an input/output device. The console (screen and Keyboard), serial 
interface, and printer are all character devices. 

A block device reads and writes blocks of 51 2 characters at a time; it can 
access any given block on demand. A block device is usually used to 
store and retrieve information: it is always an input/output device. Disk 
drives are block devices. 

3.1.2 Physical Devices and Logical Devices 

A physical device is a physically distinct piece of hardware: if an external 
device, it usually has its own box. A logical device is what SOS and the 
interpreter regard as a device: it has a name. For example, the keyboard 
and the screen are separate physical devices; but SOS regards them 
as one logical device— the console. On the other hand, if a disk drive 
contained two disks, each could be a separate logical device. 
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3.1.3 Device Drivers andD river Modules 

Programs called device drivers provide the communication link between 
the SOS kernel and input/output devices: they take the streams of 
characters coming from SOS and convert them to physical actions of the 
device, or convert device actions into streams of characters for SOS to 
process. Device drivers for the standard Apple III devices are included in 
the SOS. DRIVER file: you can change or delete these, or add new ones, 
by using the System Configuration Program (SCP) option on the Utilities 
disk , as explained in the Apple til Owner's Guide and the Apple III 
Standard Device Drivers Manual. 

The Disk III driver is included in the SOS. KERNEL file. It cannot 
be removed or changed by the user, except to specify the number 
of drives in the system. 

Each logical device connected to the system has its own device driver; 
SOS can access the logical device through its driver Related device 
drivers, such as drivers for separate logical devices on one physical 
device, can be grouped into a driver module. The drivers in a module can 
share code or system resources, such as interrupt lines. A driver module 
must be configured into the system as a package: unneeded drivers 
cannot be deleted from it. Each driver in the module is named separately. 

The SOS kernel and the interpreter only deal with logical devices 
and their drivers. Whether the logical device is one physical 
device, several physical devices, or part of a physical device, is 
academic to the interpreter writer: it is only necessary to know 
that all three cases are possible. Similarly SOS and the interpreter 
communicate with a device driver in precisely the same way 
whether or not the driver is part of a driver module, 

3.1.4 Device Names 

A logical device and its driver are both identified by a device name. 
If a driver module has several drivers, each has a different device name, 
by which it can be separately addressed. The driver module itself has 
no name, as it is never addressed as such. (The SCP refers to a module 
by the name of the first driver in it.) 




42 SOS Reference Manual 



A device name is up to 1 5 characters long: tine first is a period; the second 
is a letter; the rest can be either letters or digits, in any combination {see 
Figure 3-1). 





leiter 











leiter 



digll 




Figure 3-1. Device Name Syntax 
Some legal device names are 
.D1 

.PRINTER 

BLOCKDEVICE 

Some illegal device names are 

PRINTER (the first character is not a period) 

.BLOCK. DEVICE {only the first ciiaracter can be a period) 

.BLOCK DEVICE (a device name cannot contain a space) 

.BLOCK/DEVICE {a device name cannot contain a / ) 

A logical block device also has a volume name, discussed in section 
4-1 .3.2, which is Ihe name of the medium (for example, a flexible disk) in 
the device. In genera), ttie volume name, rather than the device name, 
should be used for communicating with the device. 
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3.2 The SOS Device System 



Since SOS accesses all devices through their drivers, the devices can be 
organized as a single-level tree, as illustrated by Figure 3-2): 



characier 
device 




character 
device 



Figure 3-2. The SOS Device System 



This system of devices underlies the system of files that will be developed 
in the next chapter. 



3.3 Device information 



Certain information about a logical device and its driver is stored in 
the driver's Device Information Block (DIB), which is broken into the 
DIB header and the DIB configuration block. The header contains 
information that SOS uses to distinguish between block and character 
devices and between devices in each class. It can be read by the 
GET_DEV_NUM and D_iNFO calls, but cannot be changed. The 
configuration block contains data that can be changed by the SCP, such 
as the baud rate of a device. The size and contents of the configuration 
block differ for each device. Some information in the DIB header can be 
used only by SOS; the information that can be read by the interpreter is 
described below. 

devname and devnum 

A device name is up to 15 characters long: the first is a period; the second 
is a letter; the rest can be either letters or digits, in any combination. The 
device name can be changed only by the SCR 
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Linked with every device name is one and only one device number. 
Access to information in the DIB is usually gained via the device 
number, which can be obtained from the device name through the 

GET DEV_NUM call Access to data stored or transmitted by a device 

is gained via the device name by accessing a similarly-named file, as 
explained in Chapter 4. 

siot num and unit num 

A device can use an interface card plugged into one of the four peripheral 
interface connectors (called slots) inside the Apple ill: such devices have 
a slot number, which indicates which of the four slots the card is plugged 
into. Adevice that does not use an interface card has a slot numberof zero. 

Related device drivers can be grouped into a driver module: each such 
driver has a unit number that indicates the placement of that driver, and 
its device, in its group. Each driver in a driver module has a separate DIB, 
but the drivers may share code. For example, the formatter drivers on the 
Utilities disk have separate DIBs but share the same code: they can be 
called separately via their unit numtjers. 

The SOS unit number has nothing to do with the logical unit 
number that the Apple III Pascal System assigns to devices. 

For more information about the internal operation of devices, see the 
Apple III SOS Device Driver Writer's Guide. 

dev type and sub type 

Apple assigns two identifiers to each device indicating the device's 
functions. The device type lets you determine whether a given device 
is a printer, a communications interface, a storage device, a graphics 
device, or whatever; the device subtype distinguishes between devices 
of the same type (to separate letter-quality printers from line printers, 
for example). 

An interpreter that wishes to communicate with a certain type of device, 
but does not know the name or number of a device of tinat type, can 
examine these identifiers to find a suitable device. 
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manuljd and versionnum 

Apple assigns two identifiers to eacli device and device driver: one lo 
identify the manufacturer of the device and driver, and one to indicate 
their version number An interpreter can use these identifiers to ensure 
compatibility with different versions of the same device. 

total blocks 

This field indicates the total number of blocks on a block device. 

ttyou wish a dev. type, sub.type. manuf.id, orversion.num to be 
assigned to a device and driver, contact the Apple Computer 
PCS Division Product Support Department, This will ensure that 
the identifiers ot each device and driver are unique and are 
available to interpreter-writers. 

3.4 Operations on Devices 



An interpreter can perform these operations on any device; 

• Find the device number associated with a given device name, 
using a GET_DEV_NUfVl call, or find the device name associated 
with a given device number, using a D INFO call; 

• Obtain the slot number, unit number, device type, device subtype, 
manufacturer's identification, and version number of a device, 
usinga D_[NFO call. 

An interpreter can perform these operations on a character 
device: 

• Receive device status information, using a D STATUS call; 

• Send device control information, using a D_CONTROL call. 
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Using the System Configuration Program, you can 

• Add a new device to tine system; 

• Remove a device from the system; 

• Alter the configuration block of a device: 

• Change the name, device type or subtype, or slot number of 
a device. 

See the Apple III Standard Device Drivers Manual, for information on 
device and control requests for specific devices, and the Apple III SOS 
Device Driver Writer's Guide for a complete specification on the 
SOS/driver interface. 

3.5 Device Calls 



The calls summarized below all operate on devices directly. The name 
of each call below is followed by its parameters (shown in boldface). 
The input parameters are directly-passed values and pointers to tables. 
The output parameters are all directly-passed results. The first list is of 
required parameters: the second, present onfy for D_INFO, is of optional 
parameters. The SOS call mechanism is explained in Chapter 8; the 
individual calls are described fully in Chapter 1 2 of Volume 2, 

D_STATUS 

[dev num, status code; value; statusjist: pointer] 

This call returns status information about the specified device by passing 
a pointer to a status list. The information can be either genera! or device- 
specific information. D_STATUS returns information about the internal 
status of the device or its driver; D_INFO returns information about the 
external status of the driver and its interface with SOS. 
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D_CONTROL 

[dev num, control_code: value; control list: pointer] 

This call sends control information to the specified device by passing a 
pointer to a control list, The information can be either general or device- 
specific information. D_CONTROL operates on character devices only. 

GET_DEV_NUM 

[dev name: pointer: dev num: result] 

This call returns the device number of the driver w/hose name is specified 
by dev_name. The ftle associated with the device need not be open. The 
device number returned is used in the D_READ, D_WRITE, D_STATUS, 
D_CONTROL, and D_INFO calls. 

D_INFO 

[dev num: value; dev name, optionjist: pointer; length: value] 

[slot num, unit num, dev_type, sub type, 

total blocks.manuf id, version num: optional result] 

This call returns the device name (and optionally, other information) 
about the device specified by dev_num. The file associated with the 
device need not be open. D_INFO returns information about the device's 
external status and interface to SOS; D_STATUS returns information 
about the internal status of the device and its driver. 
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4. T Character and Block Files 



A file is a named, ordered collection of bytes, used to store, transmit, or 
retrieve information A file is identified by its name; a byte within the file 
is identified by its position in the ordered sequence. 

SOS recognizes two types of files: character files and block files. A 
character file is treated by SOS as an endless stream of characters, or 
bytes. SOS can read or write the current byte but cannot go back to a 
previous byte or forward to a fater byte. A ctiaracter file is an abstraction 
used to represent a character device, A character file can be read-only, 
write-only, or read/write, as determined by the device it resides on. A 
character file is identified by its device name, which is defined in the 
previous chapter 

A blocl< file is treated by SOS as a finite sequence of bytes, each one 
numbered. Any byte, or group of bytes, in a block file can be accessed 
by a call to SOS, A block file is so called because it resides in a volume 
on a block device: the volume is formatted into 512-byte blocks, also 
numbered. The blocks themselves are of concern only to SOS: the 
interpreter only reads or writes bytes. 



The interpreter need only ask for the particular bytes it wants, 
using the file READ and WRITE calls. SOS translates these 
byte-oriented calls into block-oriented device requests executed 
by the device driver. SOS moves the requested bytes betw/een its 
I/O buffer and the interpreter's data buffer: the driver moves 
wfhole blocl<s containing these bytes to and from the I/O buffet 
Device requests are described in the Apple til SOS Device Driver 
Writer's Guide. 

4. 1. 1 Structure of Character and Block Files 

Character and block files are quite different in implementation, but are 
treated similarly. In fact, sequential read and write operations are the 
same; an interpreter reads a sequence of bytes from its current position 
in a block file in the same way as it reads a sequence of bytes from a 
character file. 
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The bytes in a character file are not numbered and must be accessed 
sequentially- Each read or write operation can handle a single byte or a 
sequence of up to 64K bytes. The next operation starts where the last 
left off. Figure 4-1 shows the structure of a character file. 



Rurrenl byte 
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Figure 4-1. Character File Model 

The bytes in a block file are numbered from $000000 up to SFFFFFE 
A block file can contain up to 16,772,215 bytes (one less than 16 
Megabytes). Each read or write operation can handle a single byte 
or a sequence of up to 64K bytes. The next operation can start anywhere 
in the file, with no reference to the last. For this reason, a block file is a 
random-access file. Figure 4-2 shows the structure of a block file. 

mark 'SS^' 
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Figure 4-2. Block File Model 



A block file's size is defined by its end-of-file marker, or EOF, which is 
the number of bytes that can be read from the file. The interpreter's place 
in the file is defined by the current position marker, or mark, which is the 
number of the next byte that will be read or written, 

Both of these may be moved automatically by SOS or manually by 
the interpreter 
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4.1.2 Open and Closed Fifes 

A file can be open or closed: an open file can be read from or written to; 
a closed file cannot. 



Initially, a file is closed: access to a closed file is through i[5 pathname, 
defined in section 4,2,3. 



When SOS opens a file in response to an OPEN call from an interpreter, 
SOS creates an access path to the file by placing an entry into the File 
Control Block (FCB), which is a table in memory containing information 
about all open files, and returns a reference number (ref_num) to the 
program that opened the file. This access path determines the way the file 
may be accessed (read from, written to, renamed, or destroyed). Every 
time that program accesses that file, it must use that access path and 
ref_num. Some files may have more than one access path, as shown in 
the Figure 4-3. 

Character File 




.RS232 



Block File 
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refnum = m 
mark - p 



ref mim - n 
mark = q 




Figure 4-3. Open Files 
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The character file above has two access paths, along each of which a 
program can read or write at the current byte, or character. The block file 
has two access paths, each of which can have a different current position, 
or mark, in the file. Each access path can move its own mark, and can 
read at the position it indicates. Both access paths share a common end- 
of-file marker, or EOF. 

In general, a block file can have either (a) one access path open for 
reading and writing or (b) one or more read-only access paths: it cannot 
have more than one access path if any access path can write to the file. A 
character file may have several access paths with write-access, 

SOS allows a maximum of 16 block-file access paths and 16 
character-file access paths to be open at one time, 

Each OPEN call to a file creates a new access path (with its own ref num) 
to that file, which is separate from all the file's other access paths. 

When an access path to a file is closed, its FCB entry is deleted and its 
rel_num is released for use by other files. 

Certain operations, such as reading and writing, can only be performed on 
open files; others, such as renaming, can only be performed on closed 
files. 

4.1.3 Volumes 

A volume is a piece of random-access storage medium formatted to hold 
files. A volume is mounted on a block device, and is accessed through 
that device. Both flexible disks and hard disks are volumes. 

Each logical block device corresponds to one volume at any time. If the 
device uses removable media (like flexible disks), it can access different 
volumes at different times. 
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However, a single physical device can correspond to multiple logical 
devices, each with its own driver and device name. Each of these logical 
devices would have a volume with a different name. For example, if a disk 
drive contains a fixed disk and a removable disk, it would normally be 
treated as two logical devices, each with its own volume. It would have a 
driver module containing two drivers. The two logical devices would have 
different names and unit numbers; and the two volumes would have 
different names. 

It is even possible for a single medium to be divided into multiple volumes: 
a disk holding more than 64K blocks might be so divided, as SOS cannot 
support volumes larger than 64K blocks. In this case, the physical device 
is treated as multiple logical devices: the physical device has a single 
driver module, and each logical device has a uniquely named dnverand 
volume. 

On the other hand, a driver for a disk drive containing several fixed disks 
might treat the disks as one large volume with one name. 

Having noted these special cases, we need not discuss them further They 
are discussed in the Apple III SOS Device Driver Writer's Guide, as the 
relationships between logical devices and physical devices are 
established by device drivers. Since SOS and the interpreter deal only 
with volumes and logical devices, we can ignore physical devices without 
losing generaiity. From now on, the word device will mean logical device. 

Every volume must have two special items, each in a fixed place on the 
medium: a volume directory file and a bit map. The volume directory file 
contains information about the volume (such as its name and size), and 
information about files on the volume. The bit map represents every block 
on the volume with a bit indicating whether the block is currently allocated 
to a file, or is free for use. 

4. 1.3. 1 Volume Switching 

Some devices (such as flexible-disk drives) have removable media. These 
devices can access several volumes, though only one at a time. This leads 
to problems, however, when a file has been opened on one volume in a 
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device, and subsequently that volume has been removed and another 
substituted for it. If SOS needs to access the open file on the original 
volume, it v/iW not be able to find the volume it needs. 

When this happens. SOS will request that you restore the volume to its 
original drive. It halts all operations of the computer and displays a 
message on the screen (see Figure 4-4) 



Insert volume- UTILITIES 

in dsvice: • . D 1 
then press the ALPHA LOCK ke>j tuice 



Figure 4-4. The SOS Disk Request 

naming the volume it needs and the device into which it should be 
placed. The system will vi/ait until you replace the volume and press the 
CAPS LOCK (on some keyboards called ALPHA LOCK) key on the 
keyboard twice. 

The volume-switching capability is very useful when you need to use 
many files on various volumes: it allows you to exchange volumes at 
will (when the device is idle), and still have all files accessible when they 
are needed. 

4.1.3.2 Volume Names 

A block device is accessible by two names. The first is the device name, 
defined in Chapter 3. The second, more useful, name is the volume name. 
The volume name of a block device is the name of the volume currently in 
the device: the volume name of a flexible-disk drive will change as you 
insert and remove flexible disks. A block device containing no volume 
(such as an empty flexible disk drive) has no volume name and, to SOS, 
does not exist. 
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A volume name is up to 15 characters long: \he first is a tetter; the rest 
can be letters, digits, or periods, in any combination. A volume name is 
always preceded by a slash ( / ), but the slash is not part of the name. 
SOS automatically converts all lowercase letters in a volume name 
to uppercase. The syntax of a volume name ts Identical to that of a 
file name: a diagram is shown in section 4.2.2- 

Here are a few legal volume names, with slashes: 

/PROGRAMS 

/BLOCK.FILES 

/CHAR2B 

Here are some volume names that will not work, and the reasons why: 

/BAD NAME (contains a space) 

/1 TO, 1 (first character is a number) 

/STEVE'S. PROGRAM (contains an apostrophe) 

/ANTHROPOMORPHOUS (more than 15 characters) 

We strongly recommend using the volume name, rather than the 
device name, whenever you refer to a block file. This has two 

advantages: 

• The user is protected against volume-swapping. 

• The program is more general: it can be used witti new mass- 
storage devices without modification. 

The SOS File System 



SOS organizes all fifes it can access into a hierarchical tree structure, 
called the SOS file system. The top level of this system is shown in 
Figure 4-5. 
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Figure 4-5. Top-Level Files 

The top level contains character files and volume directories. Each 
character file represents one character device; each volume directory 
represents a volume on a block device, and can directly or indirectly 
access all files on the volume. Each character file is referred to by its 
device name; each volume directory is referred to by its volume 
(preferably) or device name. 

By comparing this diagram with that of the SOS device system, you can 
see that the file system is built on top of the device system: each file 
overlays a device. 



4. 2. 1 Directory Files and Standard Files 

Since a volume on a block device can contain many files, SOS provides a 
special type of file, the directory file, to keep track of them, A directory is a 
file listing the names and locations of, as well as other information about, 
other files on the volume. The main directory on the volume is the volume 
directory, whose name is the same as its volume. The volume directory 
lists both standard files, which are block files containing data, and 
subdirectory files, which list other files. (A subdirectory file might not list 
any files: for example, if you have created a subdirectory file to list a 
series of future text files but have not yet created them.) If a directory lists 
a file, we may also say that it "owns" that file, or that is the "parent" of 
that file. 
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file 



Figure 4-6. The SOS File System 

We now have the whole tree: each node is a directory, and each leaf is a 
character or block file. We will give them names in a minute. 



4.2.2 File Names 

Each entry in a directory is listed by its file name, which distinguishes it 
from the other entries in that directory. For this reason, each file name in a 
directory must be unique. A file name is up to 15 characters long: the first 
is a letter; the rest are letters, digits, or periods, in any combination (see 
Figure 4-7). SOS automatically converts all lowercase letters in a file name 
to uppercase. 
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Figure 4-7. File Name Syntax 

Here are a few legal file names; 

MIKE.2,JULY.80 

SORTPROGRAM 

LETTER.TO.SUE 

Here are some file names that will nof work, and the reasons why; 

BAD NAME {contains a space) 

1.TO.10 (begins with a number) 

STEVE'S. PROGRAM (contains an apostrophe) 

ANTHROPOMORPHOUS (more than 1 5 characters) 

fl^^^ In earlier editions of the Apple III Owner's Guide, file names are 
called local names. 



4.2.3 Pathnames 

A pathname is a sequence of names that defines a path from the root of 
the file system, through a volume directory and possibly subdirectories, 
to a specific file, 

A pathname uniquely identifies a file. Even if two files with the same 
file name appear in the system, they can be distinguished by their 
pathnames. 
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Figure 4-8. Pathname Syntax 

A pathname is composed of names and slashes (see Figure 4-8). A 
pathname begins with a slash and a volume name; a device name; or a 
file name; more file names may follow. One slash must separate any tw/o 
successive names, and the last component of a pathname must be a 
name. As always, a volume name is preceded by a slash, and a device 
name begins with a pehod. 

Paths always begin at the root of the file system. The first component of 
the pathname determines the nature of the path. 



/vot name If the first component is a stash followed by a volume name, 
the path proceeds from the volume directory. 

dev_name If the first component is the name of a block device (which 
begins with a period), SOS automatically replaces the 
device name with the name of the volume directory of the 
volume in that device, and the path proceeds from that 
directory. 

dev_name If the sole component is the name of a character device, 
the pathname specifies its character file. No further file 
specifications are allowed after a character device name. 

Iile_name If the first component is a file name, SOS appends the 

prefix (see below) to the pathname, and the new pathname 
is evaluated again. 
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Here is our file system tree again (see Figure 4-9), this time with the file 
names filled in; 




.GRAFIX 



SOSDRIVER 



SOS DRIVER J ^^MPL^^ 



SYSTEM, PASCAL 



PHONES EXPENSES 



Figure 4-9. Pathnames 
The valid pathnames in this file system are 



.CONSOLE /BASICSTUFF 

.GRAFIX /BASICSTUFF/SOS. DRIVER 

/PASCAL1 /BASIGSTUFF/TEMPLATES 

/PASCAL1/S0S.DRIVER /BASICSTUFF/TEM PLATES/PHONES 

/PASCAL1 /SYSTEM. PASCAL /BASICSTUFF/TEM PLATES/EXPENSES 

If the volume /PASCAL 1 were installed in the device .D1 , then every 
pathname that included the volume /PASCALl would havea synonymous 
pathname using Dl : for example, /PASCAL1/S0S.DRIVER would 
specify the same file as .D1/S0S.DRIVER . 



4.2.4 The Prefix and Partial Pathnames 



The prefix is a pathname that specifies a volume directory or subdirectory 
file. When SOS boots, the prefix is set to the volume directory of the boot 
volume. 
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A partial pathname is a pathname that begins with a file name, whereas a 
full pathname begins with a volume or device name. In other words, a 
partial pathname begins with a letter, whereas a full pathname begins with 
a slash or period. When SOS receives a partial pathname, it concatenates 
the prefix to that pathname with a slash, forming a full pathname. The 
effect is to allow you to specify a "current directory", or prefix, and referto 
files owned by that directory without having to specify the directory's 
pathname each time. For example, the pref ix /PASCAL1 and the partial 
pathname SOS.DRIVER form the full pathname /PASCAL1/S0S.DRIVER. 

The prefix always specifies a volume directory or subdirectory file. The 
prefix never specifies a standard or character file. 

The SOS prefix is not the Pascal prefix. The two may or may not 
have the same value. 

4.3 File and Access Path Information 



An interpreter often needs information about a file or an access path. 
Information about a block file is stored in the file's directory entry. 
Information about a block file access path is stored in its FCB entry. This 
section describes file information and access path information for block 
files only Information about a character file is stored as the device 
information of its respective character device (see section 3.3). No 
corresponding information about an access path to a character file is 
available through SOS. 

The various items of information about a file will be named in boldface, 
and the same names will be used when these items appear as fields in 
directories (in Chapter 5) and as parameters for SOS calls (in Chapter 8 
and in Volume 2). 

4. 3. 1 File In formation 

Certain information about a block file, such as a file's name, belongs to the 
file itself rather than to any of its access paths. This information is stored 
in that file's directory entry (see section 5,2.4). 
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An interpreter can read the file information in the directory entry with a 
GET_FILE_INFO call or change it with aSET_FILE_INFO call, both 
described in Chapter 10 of Volume 2. No change, however, can be made 
to any of the file information if the file is open: a SET_FILE_INFO call to 
do so will have no effect until the file is closed. 

This information about a file is kept in the director/ entr/: 

lilename 

A closed block file is accessed by its file^name. The file name of a block 
file can be changed, but only when the file is closed. Only the last file 
name in a pathname can be changed, because the preceding names are 
the names of open directory files, which are shared with other files. 



Every block file has an access attribute field, which determines tfiewaysin 
which you may use that file. The access attributes can be set to prevent 
you from reading from, writing to, renaming, or destroying a file. It can 
also tell you whether a file's contents have been changed since the last 
time a backup copy of the file was made, 

EOF and blocks_used 

The number of bytes in a block file is specified by the end-of-file pointer, 
or EOF. The number of blocks physically used by the file is specified by 
the blocks^ used item. \n sparse files, which we will see later the EOF and 
blocks^used numbers may not correspond as you might expect. 




Ad access to information atJOut a closed block file is througfi its 
file name 



access 




GET_FILE_tNFO returns the cifrrent value of EOF and 
blocks used only if the file is closed. If it is open, GET_EOF 
returns'the correal value ol EOF. GET_FILE_INFO returns the 
values EOF and blocks used had when the file was opened. 
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storage type, file type, and aux type 

Three items describe the external and internal arrangement of each block 
file. The storage_type indicates whether the file is a directory file or a 
standard file, and how the file is stored on its block device: this item is 
used only by SOS. The filejype classifies the contents of the file; and the 
aux_type can be used by an interpreter as an additional description of the 
contents of the file: these two items are used only by the interpreter, 

A description of the identification codes and their meanings is given later 
in this chapter. 

creation and lasl mod 

These items record the dates and times at which a block file was initially 
created and last updated. These values are drawn from the system clock 
or the last known time, 

4.3.2 Access Path Information 

other information about a block file, such as an interpreter's position in a 
file, belongs to the access path rather than the fite itself This information 
is stored in the access path's entry in the File Control Block. 

Access path information can be changed only while that access path is 
open. When the access path is closed, certain items, such as the mark, 
disappear, and others, such as the EOF, update the file information in the 
directory entry. 

This information about the access path is kept in the FCB entry: 
ref num 

When an access path to a file is opened, SOS assigns that access path a 
unique reference number, or ref_num. All subsequent references to that 
access path must be made with that ref_num. 

EOF and mark 

Each access path to an open block file has one attribute defining the end 
of file, the EOF, and another defining the current position in the file, the 
mark. Both of these may be moved automatically by SOS or manually by 
the interpreter 
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The EOF pointer is the number of bytes in the file. This is equivalent to 
pointing one position beyond the last byte in the file, since the first byte is 
byte number 0: in an empty file (containing zero bytes), EOF points at byte 
number 0. The value of the mark cannot exceed the value of EOF. 



The EOF is peculiar in that it appears both in the file's directory entry and 
in the access path's FCB entry. When a file is open for writing, the two 
values of the EOF may differ The current EOF is stored in the access 
path's FCB entry; this EOF is returned by a GET_EOF call to the ret_num- 
The value of EOF in the file's directory entry is updated oniy when the 
access path is closed: this EOF is returned by a GET_FILE_INFO call to 
the file name. 

It Is impossible for two access paths to have different EOF values, for in 
order to change the EOF, an access path must have write-access. If it 
does have write-access, it must be the only access path to that file. 

The mark automatically moves forward one byte for every byte read from 
or written to the file. Thus, the mark always indicates where the next byte 
will be read or written. 



If, during a WRITE operation, the mark meets the EOF, both the mark and 
the EOF are moved forward one position for every additional byte written 
to the file. Thus, adding bytes to the end of the file automatically moves 
the EOF up to accommodate the new information. Figure 4-1 shows the 
automatic movement of EOF and mark, 
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Figure 4-10. Automatic Movement of EOF and Mark 



An interpreter can manually move the EOF to place it anywhere from the 
current mark position to the maximum byte position possible <see Figure 
4-1 1 ). The mark can also be placed anywhere from the first byte in the file 
to the current position of the EOF. 
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Figure 4-11. Manual Movement of EOF and Mark 

The EOF is read by the GET_EOF call and manually set by the 

SET_EOF call; the mark is read by the GET MARK call and manually 

set by the SET_MARK call. 

level 

Each access path is given a level when it is opened. The level of the 
access path is the value of the system file level at the time the access path 
was opened. An interpreter can group files by file levels (for example, have 
user files open at one level, while system files are open at another), and 
perform group operations on files of like levels. 

The system file level has the value i , 2, or 3. When the system is booted, 
the level is set to 1 . It can be changed by the SET_LEVEL call, and read 
by the GET_LEVEL call. One use of the file level is to close all files 
opened by a user program when the interpreter exits tfiat program. 

This is done as follows: When the interpreter enters the program, it 
raises the system file level. Thus alt files opened by the program will have 
a higher level than, say. .CONSOLE or the interpreter file, When the 
interpreter exits the program, it issues a FLUSH call or CLOSE call with a 
ref_num of $00, which closes all files at a level equal to or higher than the 
system file level. Then the interpreter lowers the system file level. 
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4.3.3 Ne wline Mode Inform a tion 

Certain information about a file, called newline-mode informailon. is 
associated eitfier witfi the file itself or with an access path to the file, 
depending on the kind of file. A character file's newline-mode information 
is associated with the file and its device; a block file's newline-mode 
information is associated with an access path to the file, and can differ 
from one access path to another. 

When SOS reads from an open file, it can read input as a continuous 
stream of characters or as a series of lines. In the first case, you ask SOS 
to read a specific number of bytes: when this number have been read or 
when the current position has reached the end of fi!e. the READ operation 
terminates. In the second case, called newline mode, the READ will also 
terminate if a specified character, the newline character, is read. The 
newline character is usually the ASCII CR ($0D), but can beany hex value 
from $00 to $FF, The newline character is called the termination character 
or line-termination character in the Apple III Standard Device Drivers 
Manual. 

Newline mode is supported on both character and block files, so that file 
input/output can be device independent. For exampte, a program that 
reads a line of text from a file can treat the keyboard and a disk file exactly 
the same way, 

is newline and newllne char 

Newline mode is controlled by two values: is_newline turns newline mode 
on or off; newlifie_char sets the newline character These two values are 
set by the NEWLINE call to the access path's ref_num. 

For a block file, each access path can have separate is.newline 
and newline.cfiar values, A character file also has is^newiine and 
newline.char values, which are also changed by a NEWLINE call 
to an access path's ref_num, but they are the same for all access 
paths, If either value is changed for one access path, it is 
changed for all. 
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4.4 Operations on Fifes 

These operations can be performed on all files: 

• OPEN and CLOSE to control access, and READ and WRITE (if its 
access attributes allow) to transfer information from or to the file. 

• Change is_newline and newlir>e_char for an access pathi, using the 
NEWLINEcall. 

These operations can be performed only on block files: 

• Examine or change file information, including the name, access, 
file type, and modification date, using the GET_FILE_INFO and 
SET_FILE_INFO calls. 

These operations can be performed only on closed block files: 

• CREATE a new file; 

• DESTROY an existing file; 

These operations can be performed only on standard files open for 
writing: 

• Set and read the EOF pointer, using the SET^EOF and 
GET_EOF calls, 

• Set and read the current position mark, using the SET MARK 

and GET_MARK calls. 

These operations can be performed on directory files: 

• OPEN and CLOSE the file. 

• READ the ffle, if it Is open. 

• DESTROY the file, if it is empty and closed- 
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4.5 File Calls 



These calls deal with files: the calls CREATE through OPEN operate on 
closed files; the calls NEWLINE through GET_LEVEL operate on open 
files. The name of each call below is followed by its parameters (In 
boldface). The input parameters are directly-passed values and pointers 
to tables. The output parameters are all directly-passed results. The first 
list is of required parameters; the second list, present for some calls, is of 
optional parameters. The SOS call mechanism is explained In Chapters; 
the individual calls are described fully in Volume 2, Chapter 9. 

CREATE 

[pathname, optionjist: pointer; length: value] 

[file type, aux type, storage type, EOF: optional value] 

This call creates a standard file or subdirectory file on a block device. 
A file entry is placed in a directory, and at least one block is allocated. 

DESTROY 
[pathname: pointer] 

This call deletes the file specified by the pathname parameter by marking 
the file's directory entry inactive. DESTROY releases all blocks used by 
that file back to free space on that volume. 

The file can be either a standard or a subdirectory file. A volume directory 
cannot be destroyed except by physically reformatting the medium, A 
character file can be removed from the system by the System 
Configuration Program. 

RENAME 

[pathname, new pathname: pointer] 

This call changes the name of the file specified by the pathname 
parameter to that specified by new_pathname. Only block files may be 
renamed; character files are "renamed" by the System Configuration 
Program. 
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SET_FILE_INFO 

[pathname, optionjist: pointer; length: value] 

[access, tile type, aux type, last_niod: optional value] 

This call modifies information in thie directory entry of the file specified by 
the pathname parameter. Only block files' information can be modified; 
character files have no such information associated with them 

You may perform a SET FILE_INFO on a currently-open file, but the 

new information will not take effect until the next time the file is OPENed. 

GET_FILE_INFO 

[pathname, optionjist: pointer; length: value] 

[access, file type, aux type, storagejype, EOF. blocks, 
last_mod: optional result] 

This call returns information about the block file specified by the 
pathname parameter. 

VOLUME 

[dev name, vol name: pointer; blocks, free blocks: result] 

When given the name of a device, this call returns the volume name of the 
volume contained in that device, the number of blocks on that volume, 
and the number of currently unallocated blocks on that volume. 

SET_PREFIX 
[pathname: pointer] 

This call sets the operating-system pathname prefix to that specified in 
pathname. 

GET_PREFIX 

[pathname: pointer; length: value] 

This call returns the current system pathname prefix. 
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OPEN 

[pathname: pointer; ref num: result; optionjist: pointer; length: value] 
[req access, pages: optional value; io_buffer: optional pointer] 

This call opens an access path to the file specified by patKname for 
reading or writing or both. SOS creates an entry in the file control block 
and an 1/0 buffer. 

NEWLINE 

[ref num, is newline, newline_char; value] 

This call aWows the caller to selectively enable or disable "newline" read 
mode. Once newline mode has been enabled, any subsequent read 
request will immediately terminate if ttie newline character is encountered 
in the input byte stream. 

READ 

[ref num: value; data buffer: pointer; request count, 
transfercount: value] 

This call attempts to transfer request _count bytes, starting from the 
current position (mark), from the file specified by re(_num into the buffer 
pointed to by data_buffer. If newline read mode is enabled and the 
newline character is encountered before request_count bytes have been 
read, then the transfer_count parameter will be less than request_count 
and exactly equal to the number of bytes transferred, including the 
newline byte. 

WRITE 

[ref num: value; data buffer: pointer; request_ count: value] 

This call transfers request_count bytes, starting from the current file 
position (mark), from the buffer pointed to by data^buffer to the open file 
Specified by ref_num. 
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CLOSE 

[refnum: value] 

This call closes the file access path specified by ret_num. Its file-control 
block is released, and if the file is a block file that has been written to, its 
write buffer is emptied. The directory entry for the file, if any, is updated. 
Further file operations using that ref_num will fail. If ref^num is $00, ail files 
at or above the system file level are closed. 

FLUSH 

[reJ_num: value] 

This call flushes the file access path specified by ref^num. If the file is a 
block file that has been whtten to, its I/O buffer is emptied. The access 
path remains open. If rel_num is $00, all files at or above the system file 
level are flushed, 

SET_MARK 

[ref num, base, displacement; value] 

This call changes the current file position (mark) of the file access path 
specified by re(_num. The mark can be changed to a position relative to 
the beginning o?the file, the end of the file, or the current mark, 

GET_MARK 

[ref_num: value; mark: result] 

This call returns the current fife position {mark) of the file access path 
specified byref_num. 

SET_EOF 

[ref_num, base, displacement: value] 

This call moves the end-of-file marker (EOF) of the specified block file to 
the indicated position. The EOF can be changed to a position relative to 
the beginning of the file, the end of the file, or the current mark. 
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if the new EOF is less than the current EOF, then empty blocks at the end 
of the file are released to the system and their data are lost. The converse 
is not true: if the new EOF is greater than the current EOF, then blocks 
are not allocated, creating a sparse file; reading from these newly created 
positions before they are whtten to results in $00 bytes. 

GET_EOF 

[ref num; value, EOF: result] 

This call returns the current end-of-file (EOF) position of the file specified 
by ref_num, 

SET_LEVEL 
[level: value] 

This call changes the current value of the system file level. All subsequent 
OPENS will assign this level to the files opened. All subsequent CLOSE 
and FLUSH operations on multiple files (using a rel_num of $00) will 
operate on only those files that were opened with a level greater than or 
equal to the new level. 

GET_LEVEL 
[level: result] 

This call returns the current value of the system file level. See 
SET_LEVEL, OPEN, CLOSE, and FLUSH. 
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When a program accesses a block device, it actually accesses the volume 
that corresponds to that device. You have already learned of the 
hierarchical tree structure used by SOS in its filo organization, of the 
naming conventions used to access any file within the tree structure, and 
of the logical structure of a file as a sequence of bytes; this chapter 
explains the physical implementation of these structures on any volume. 

The first part of the chapter (section 5.1) discusses what is on a volume, 
the second (section 5,2) describes directory files, the third part of the 
chapter (section 5.3) discusses standard files, and the final part of the 
chapter (section 5,4) provides a graphic summary of the organization of 
information on volumes. 

The focus of this chapter is on how SOS works, not on how to use it. For 
this reason, we have chosen to explain details of implemention that are 
not strictly necessary for an interpreter writer to know, in order to make 
the working of SOS more concrete. The only section that is of immediate 
practical use to an interpreter writer is section 5.2 on the formats of 
directory tiles. The rest of the chapter explains the implementation of the 
file system: these sections should be regarded as examples, not as 
specifications. 

In this manual, we will distinguish the SOS interface, which is supported, 
and the SOS implementation, which is not. We will support the 
hierarchical tree structure of the file system and the logical structures of 
character and block files. We will also support the storage formats of 
directory headers and entries, although they may be expanded by 
appending new fields. However, we may change volume formats and the 
storage formats of standard files. 

Programmers should not rely on the details of implementation, as 
we may change the storage formats of files in order to improve 
performance. An interpreter that uses the READ and WR ITE calls 
to access files, and interprets directories as we explain here, will 
work with future versions of SOS. An interpreter that relies on the 
current disk-allocation scheme or index-block structure may not 
work with future versions. 
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5. 1 Format of Information on 
a Volume (SOS 1.2) 



This section explains how SOS 1 ,2 organizes information on a 280-block 
flexible disk: it should be regarded as an example, not a general 
specification for volume formats. 

In accessing a volume, SOS requests a logical block from the device 
corresponding to that volume. Logical blocks may be supported physically 
by tracks and sectors, or cylinders and heads, or other divisions. This 
translation is done by the device driver the physical location of 
information on a volume is unimportant to SOS. This chapter discusses 
the organization of information on a volume in terms of blocks, numbered 
starling with 0. 

When the volume is formatted, information needed by SOS is placed in 
specific logical blocks. A bootstrap loader program is placed in blocks 
and 1 of the volume. This program loads SOS from the volume when 
CONTROL-RESET is pressed. Block 2 of the volume is the first block, or 
key block, of the volume directory file: it contains descriptions and 
locations of all the files in the volume directory, as well as the location of 
the volume bit map. The volume directory occupies a number of 
consecutive blocks (4 forSOS1.2),and normally is immediately followed 
by the volume bit map, which records whether each block on the volume 
is used or unused. The volume bit map occupies consecutive blocks, one 
for every 4,096 blocks (or fraction thereof) on the volume. The rest of the 
blocks on the disk contain either subdirectory file information, standard 
file information, or garbage (such as parts of deleted files). The first 
blocks of a volume look something like this (Figure 5-1): 
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Figure 5-1. Blocks on a Volume 

The precise formal of the volume directory, volume bit map, subdirectory 
files and standard files are explained in the following sections. 



5.2 Format of Directory Files 



The format of the information contained in volume directory and 
subdirectory files is quite similar Each directory file is a linked list of one 
or more blocks: each block contains pointers to the preceding and 
following blocks, aseriesof enthes, and unused bytes at the end. The first 
block, called the key block, has no preceding block, so its preceding-block 
pointer is zero; the last block has no following block, so its following-block 
pointer is zero. 

Most entries in a director/ describe other files, which can be either 
standard files or directories; these entries are called file entries. The first 
entry in the key block of a directory contains information about the 
directory itself, not about another fife: this entry is called the directory 
header. 



The format of a directoiy file is represented in Figure 5-2. 
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Figure 5-2, Directory File Formal 
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The header entry is the same length as all other entries. As will be 
described below, the only organizational difference between a volume 
directory file and a subdirectory file Is in the header. 

5.2.7 Pointer Fields 

The first four bytes of each block used by a directory file contain pointers 
to the preceding and succeeding blocks, respectively, of the directory file. 
Each pointer is a two-byte logical block number, low byte first, high byte 
second. The key block of a directory file has no preceding block: its first 
pointer is zero Likewise, the last block in a directory file has no successor 
its second pointer is zero. If a directory occupies only one block, both 
pointers are zero. 




,1 A pointer of value zero causes no ambiguity: no directory block 
could occupy block 0, as blocks and 1 are reserved for the 



bootstrap loader 

All block pointers used by SOS have the same format: low byte first, high 
byte second. 

5.2.2 Volume Directory Headers 

Block 2 of a volume is the key block of that volume's directory file. One 
finds the volume directory header at byte position 0004 of the key block, 
immediately following the block's two pointers. 

Figure 5-3 illustrates the structure of a volume directory header: following 
the figure is a description of each field. If you compare Figure 5-3 with 
Figure 5-4, you will notice that the two header types have the same 
structure for the first 12 fields, from storagejype to file count; after that, 
the two diverge. However, similarly named fields have different meanings 
for the two types, so we have described each type separately 



80 SOS Reference Manual 



length 
1 byte 

IS hyles 
8 bytes 

4 bytes 

1 byte 
1 byte 
1 byte 
1 byte 
1 byte 

2 bytes 
2 bytes 
2 bytes 



if 



storage_type name length 



tile name 



reserved 



creation 



version 



mfn version 



access 



entry length 



cnlr!es_per_bloctc 



tile count 



bit_map_ pointer 



total blocks 



Byte of 
Block 

S05 

$13 
J14 

$1B 
SIC 
$1D 

$ie 

$1F 
$20 
$21 
S22 
123 
$24 
$25 

$26 
$27 

$28 
329 

$2A 



Figure 5-3. The Volume Directory Header 
storage type and natnejenglh (1 byte); 

Two four-bit fields are packed into this byte. A value of $F in thte high four 
bits {the storage_lype) identifies the current block as the key block of a 
volume directory file. The low four bits contain the length of the volume's 
name (see the Itle name field, below). The name length can be changed 
by a RENAME calL 



file_name (15 bytes): 

The first name_length bytes of this field contain the volume's name. This 
name must conform to the file name (or volume name) syntax explained 
in Chapter 4. The name does not begin with the slash that usually 
precedes volume names. This field can be changed by the RENAME call. 
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reserved (8 bytes): 

This field is reserved for future expansion of tfie file system, 
creation (4 bytes): 

This field holds the date and time at which this volume was initialized. The 
format of these bytes is described in section 5.4.2.2. 

version (1 byte): 

This is the version number of SOS under which this volume was initialized. 
This byte allows newer versions of SOS to determine the format of the 
volume, and adjust their directory interpretation to conform to older 
volume formats. 



min version (1 byte): 

This is the minimum version number of SOS that can access the 
information on this volume. This byte allows older versions of SOS to 
determine whether they can access newer volumes. 



access {1 byte): 

This field determines whether this volume directory may be read, written, 
destroyed, and renamed. The format of this field is described in section 
5.4.2.3. 

entry length (1 byte); 

This is the length in bytes of each entry in this directory. The volume 
directory header itself is of this length. 




For SOS 1 .2, version - 0. 




For SOS 1 .2, rtwi version = 0. 




For SOS 1 .2, entry length = $27. 




entriesperblock (1 byte): 

This is the number of entries that are stored in each block of the 
directory file. 



filecouni {2 bytes): 

This is the number of active file entries in this directory file. An active file 
is one whose storagejype and name_length are not 0. See section 5.2.4 
for a description of file entries, 

bil map pointer (2 bytes) : 

This is the blocl< address of the first block of the volume's bit map. The bit 
map occupies consecutive blocks, one for every 4,096 blocks (or fraction 
thereof) on the volume. You can cafculate the number of blocks in the bit 
map from the total_blocks value, described below. 

The bit map has one bit for each block on the volume: a value of 1 means 
the block is free: means it is in use. 

total blocks (2 bytes): 

This is the total number of blocks on the volume. 

5.2.3 Subdirectory Headers 

The key block of every subdirectory file is pointed to by an entry in 
another directory (explained below). A subdirectory header begins at 
byte position $0004 of the key block of that subdirectory file, immediately 
following the two pointers. Its internal structure is quite similar to that of a 
volume directory header. Figure 5-4 illustrates the structure of a 
subdirectory header. A description of all the fields in a subdirectory 
header follows the figure. 




For SOS 1.2, entries per btock = $0D 
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Figure 5-4. The Subdirectory Header 



storage type and name_length (1 byte): 

Two four-bit fields are packed into this byte. A value of $E in the high four 
bits {the storage Jype) identifies the current block as the key block of a 
subdirectory file. The low four bits contain the length of the subdirectory's 
name {see the file name field, below). The name length can be changed 
by a RENAME calk 



file_name (15 bytes); 

The first name-length bytes of this field contain the subdirectory's name. 
This name must conform to the file name syntax explained in Chapter 4. 
This field can be changed by the RENAME call. 




reserved (8 bytes) : 

This field is reserved for future expansion of tlie file system, 
creation (4 bytes); 

This is the date and time at which this subdirectory was created. The 
format of these bytes is described in section 5.4.2,2. 

version (1 byte): 

This is the version number of SOS under which this subdirectory was 
created. This byte allows newer versions of SOS to determine the format 
of the subdirectory, and to adjust their directory interpretations 
accordingly. 



min version (1 byte): 

This is the minimum version number of SOS that can access the 
information in this subdirectory. This byte allows older versions of SOS to 
determine whether they can access newer subdirectories. 



access {1 byte): 

This field determines whether this subdirectory may be read, written, 
destroyed, and renamed. The format of this field is described in section 
5.4.2.3, A subdirectory's access byte can be changed by the ' 
SET_FILE_INFO call. 

entry iength (1 byte): 

This Is the length in bytes of each entry in this subdirectory. The 
subdirectory header itself is of this length. 




For SOS 1,2, version = 0. 




For SOS 1.2, min version = 0. 




For SOS 1.2, entry length = $27. 




entries_per_block (1 byte): 

This is the number of entries ttiat are stored in eacin block of ttie directory 
file. 



file_couni (2 bytes): 

Ttiis is ttie number of active file entries in this subdirectory file. An active 
file is one whose storage_type and name_ length are not 0. See the next 
section for more information about file entries. 

parentpointer (2 bytes): 

This is the block address of the directory file block that contains the entry 
for this subdirectory. This two byte pointer is stored low byte first, high 
byte second. 

parent en try number (1 byte): 

This is the entry number for this subdirectory within the block indicated 
by parent pointer. 

parent_entry_lengtli (1 byte): 

This is the entry Jenglh for the directory that owns this subdirectory file. 
Note that with these last three fields one can calculate the precise position 
on a volume of this subdirectory's file entry. 



5.2.4 File Entries 

immediately following the pointers in any block of a directory file are a 
number of entries. The first entry in the key block of a director/ file is a 
header; all other entries are file entries. Each entry has the length specified 
by that directory's enlry_iength field, and each file entry contains 
information that describes, and points to, a single subdirectory file or 
standard file. 




For SOS 1 .2, entffes per block = $0D. 




For SOS 1.2. parent entry jer^th =$27. 
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An entry in a directory file may be active or inactive; tinat is, it may or may 
not describe a file currently in the directory. If it is inactive, the 
storage type and name length fields are zero. 

The maximum number of entries, including the header, in a block of a 
directory is recorded in the entries_per_block field of that directory's 
header The total number of active fiie entries, not including the header, is 
recorded in the file_counl field of that directory's header. 

Figure 5-5 describes the format of a file entry. 
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Figure 5-5. The File Entry 
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storage type and namejength (1 byte): 

Two four- bit fields are packed into this byte. The value in the high-order 
four bits (the storagejype) specifies the type of file this entry points to. 
The values $1 , $2, $3, and $D denote seedling, sapling, tree, and 
subdirectory files, respectively. Seedling, sapling, and tree files, the three 
forms of a standard file, are described later in this chapter. The low-order 
four bits contain the length of the file's name (see the tile_name field, 
below). If a file entry is inactive, the storagejype and name_length are 
zero. The name^lenglh can be changed by a REN AfvIE call, 

fHe_name (15 bytes): 

The first name_length bytes of this field contain the file's name. This 
name must conform to the file name syntax explained in Chapter 4. This 
field can be changed by the RENAME call. 

Iile_type (1 byte): 

This specifies the internal structure of the file. Section 5.4.2,3 contains a 
list of the currently defined values of this byte. 

key pointer {2 bytes) : 

This is the block address of the key block of the subdirectory or standard 
file described by this file entry. 

blocks used {2 bytes): 

This is the total number of blocks actually used by the file. For a 
subdirectoiy file, this includes the blocks containing subdirectory 
information, but not the blocks in the files pointed to. For a standard file, 
this includes both informational blocks (index blocks) and data blocks. 
Refer to section 5.3 for more information on standard files. 

EOF (3 bytes): 

This is a three-byte integer, lowest bytes first, that represents the total 
number of bytes readable from the file. Note that in the case of sparse 
files, described later in the chapter, EOF may be greater than the number 
of bytes actually allocated on the disk. 
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creation {4 bytes): 

This is the date and time at which the file pointed to by this entry was 
created, The format of these bytes is described in section 5.4.2.2. 

version (1 byte): 

This is the version number of SOS under which the file pointed to by this 
entry was created. This byte allows newer versions of SOS to determine 
the format of the file, and adjust their interpretation processes accordingty. 



min versfon (1 byte): 

This is the minimum version number of SOS that can access the 
information in this file. This byte allows older versions of SOS to determine 
whether they can access newer files. 



access (1 byte): 

This field determines whether this file can be read, written, destroyed, 
and renamed. The format of this field is described in section 5.4.2.3. The 
value of this field can be changed by the SET FILE_INFO call. 

aux type (2 bytes): 

This is a general-purpose field in which an interpreter can store additional 
information about the internal format of a file. For example, BASIC uses 
this field to store the record length of its data files. This field can be 
changed by the SET_FILE_INFO call. 

lasl mod (4 bytes): 

This is the date and time that the last CLOSE operation after a WRITE 
was performed on this file. The format of these bytes is described in 
section 5.4.2.2. This field can be changed by the SET_FILE_INFO call. 





For SOS 1.2, min version = 0. 
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headerpointer (2 bytes): 

This field is the block address of the l<ey block of the directory that owns 
this file entry. This two byte pointer is stored low byte first, high byte 
second. 

5.2.5 Field Formats in Detail 

Several of the fields above occur in more than one l<ind of directory entry. 
Therefore, we have pulled them out for more detailed explanation here. 

5.2.5. 1 The storage Jype Field 

The storage_type, the high-order four bits of the first byte of an entry, 
defines the type of header (if the entry is a header) or the type of file 
described by the entry. 

$0 indicates an inactive file entry 
$1 indicates a seedling file entry 

( 0<=EOF<= 512 bytes) 
$2 indicates a sapling file entry 

(512<EOF<= 128K bytes) 
$3 indicates a tree file entry 

(128K<EOF<16M bytes) 
$D indicates a subdirectory file entry 
$E indicates a subdirectory header 
$F indicates a volume directory header 

SOS automatically changes a seedling file to a sapling file and a sapling 
file to a tree file when the file's EOF grows into the range for a larger type. 
If a file's EOF shrinks into the range for a smaller type, SOS changes a 
tree file to a sapling file and a sapling file to a seedling file. 

5.2.5.2 The creation and lastjnod Fields 

The date and time of the creation, and of the last modificatton, of each file 
and directory are stored as two four-byte values {see Figure 5-6): 
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Figure 5-6. Date and Time Format 



The values for the year, month, day, hour, and minute are stored as 
unsigned binary integers, and may be unpacked for analysis. Note that 
the SOS calls GET_TIME and SET_TIME represent dates and times 
differently. 

5.2.5.3 The access A ttributes 

The access attribute field determines whether the file can be read from, 
written to, deleted, or renamed. It also tells whether a backup copy of the 
file has been made since the file's last modification (see Figure 5-7). 
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Figure 5-7. The access Attribute Field 

A bit set to 1 indicates that the operation is enabled; a bit cleared to 
indicates that the operation is disabled. The reserved bits are always 0. 

SOS sets bit 5 (the backup bit) of the access field to 1 whenever the file is 
changed (that is, after a CREATE, RENAME, CLOSE after WRITE, or 
SET_FILE_INFO operation). This bit is cleared to whenever the file is 
copied by Backup III. This lets Backup III selectively back up files that 
have been changed since the last backup was made. 
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Only SOS may change bits 2-4. Only SOS and Backup I 
change bit 5. 



I may 



5.2.5.4 The filejype Field 

The file_type field within an entry identifies the type of file described by 
that entry. This field should be used by interpreters to guarantee file 
compatibility from one interpreter to the next. The values of this byte are 
defined below: 



$00 


Typeless file (BASIC unknown file) 


$01 


File containing all bad blocks on the volume 


$02 


Pascal or assembly-language code file 


$03 


Pascal text file 


$04 


BASIC text file; Pascal ASCII file 


$05 


Pascal data file 


$06 


General binary file 


$07 


Font file 


$08 


Screen image file 


$09 


Business BASIC program file 


$0A 


Business BASIC data file 


$0B 


Word Processor file 


$0C 


SOS system file (DRIVER, INTERR KERNEL) 


$0D,$0E - 


SOS reserved 


$0F 


Directory file (see storagejype) 


$10-$BF ^ 


SOS reserved 


$C0-$FF- 


ProDOS reserved 



5. 2. 6 Reading a D irectory File 

Reading a directory file is straightforward, but your program must be 
written to allow for possible changes in theentry length and the number of 
entries per block: future versions of SOS may change these by adding 
more information at the end of an entry. Since these values are in the 
directory header, this flexibility is not difficult to achieve. 
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The first step in reading a directory file is to open an access path to the 
file, and obtain a ref_num. Using the ref_num to identity the file, read the 
first 512 bytes of the file into a buffer. The buffer contains two two-byte 
pointers, followed by the entries: the first entry is the directory header. 
Bytes $1 F through $20 in the header (bytes $23 through $24 in the buffer) 
contain the values of entryjength and entries per block. 

Once these values are known, an interpreter can read through the enthes 
in the buffer, using a pointer to the beginning of the current entry and a 
counter indicating the number of entries examined in the current block. 
Any entry whose first byte is zero is ignored. When the counter equals 
entries_per_block, read the next 51 2 bytes of the file into the buffer When 
a READ returns a bytes read parameter of zero, you have processed the 
entire directory file, 

5.3 Storage Formats of Standard Files 



Each active entry in a directory file points (using its key_pointer field) to 
the key block of another directory file or to the key block of a standard file. 
An entry that points to a standard file contains information about the file: 
its name, its size, its type, and so on. 

Depending on its size, a standard file can be stored in any of the three 
formats explained below: seedling, sapling, and tree. An interpreter can 
distinguish between these three (using the file entry's storagejype field), 
but it need not, for an interpreter reads every standard f ite in exactly the 
same way, as a numbered sequence of bytes. Only SOS needs to know 
how a file is stored. Nevertheless, we think it is useful for programmers to 
understand how SOS stores data on a volume. 

The storage formats in this section apply to SOS 1 .2, They may 
change in future versions of SOS. 

5.3. 1 Growing a Tree File 

As a tree file grows, it goes through three storage formats, as explained in 
the following scenario. In the scenario, we start with an empty formatted 
volume, create one file, then increase its size in stages. 



I 
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This scenario is based on the block-allocation scheme used by 
SOS 1 ,2 on a 2e0-block flexible disk, which contains four blocks 
of volume directory, and one block of volume bit map. This 
scheme is subject to change in future versions of SOS. 

Larger capacity volumes might have more blocks in the volume bit map, 
but the process would be the same. 

A formatted, but otherwise empty, 280-block SOS disk is used like this; 

B)ocl(S 0-1 : Bootstrap Loader 

Blocks 2-5 Volume Directory 

Blocks : Volume Bit Map 

Blocks 7-279 : Unused 



If you open a new standard file, one data block is immediately allocated 
to that file. An entry is placed in the volume directory, and it points to 
block 7, the new data block, as the key block for the file. The volume now 
looks like this: 



Blocks 0-1 

Blocks 2-5 
Blocks 
Block 7 
Blocks 8-279 



Bootstrap Loader 
Volume Directory 
Volume Bit Map 
Data Block 
Unused 



Key Block Pointer 



data 
block 



This is a seedling file: its key block contains up to 512 bytes of data. If you 
write more than 512 bytes of data to the file, the file grows into a sapling 
file. As soon as a second block of data becomes necessary, an index 
block is allocated, and it becomes the file's key block: this index block 
can point to up to 256 data blocks (two-byte pointers). A second data 
block (for the data that won't fit in the first data block) is also allocated. 
The volume now looks like this: 
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Blocks 0-1 
Blocks 2-5 
Block 6 
Block 7 
Block 8 
Block 9 



Bootstrap Loader 
Volume Directory 
Volume Bit Map 
Data Block 
Index Block0 
Data Block 1 



Blocks 10-279; Unused 



Key Block Pointer 



index 
block 



data 




data 


block 




block 1 



This sapling file can hold up to 256 data blocks: 128K of data. If the file 
becomes any bigger than this, the file grows again, this time into a free 
We. A master index block is- allocated, and it becomes the file's key block: 
the master index block can point to up to 128 index blocks, and each of 
these can point to up to 256 data blocks. Index block becomes the first 
subindex block, which is an index block pointed to by the master index 
block. In addition, a newsubindex block is allocated, and a new data 
block to which it points. Here's a new picture of the volume: 



Blocks 0-1 
Blocks 2-5 
Block 6 
Block 7 
Blocks 
Blocks 9-263 
~* Block 264 
Block 265 
Block 266 
Blocks 267-279 



As data are written to this file, additional data blocks and index blocks are 
allocated as needed, up to a maximum of 129 index blocks {one master 
index block and 128 subindex blocks), and 32,768 data blocks, for a 
maximum capacity of 1 6,777,21 5 by tes of data in a file. If you did the 
multiplication, you probably noticed that we lost a byte somewhere. The 
last byte of the last block of the largest possible file cannot be used 
because EOF cannot exceed 16,777,215. If you are wondering how such a 
large file might fit on a small volume such as a floppy disk, refer to the 
section on sparse files, later in this chapter. 



Bootstrap Loader 
Volume Directory 
Volume Bit Map 
Data Block 
Index Blockfl 
Data Blocks 1-255 
Master Index Block 
Index Block 1 
Data Block 256 
Unused 



Key Block Pointer 



master 
index 
block 



index 




index 


block 




block 1 



/ 



data 




data 




data 


blocks 


• * 4 


block 255 




block 2S6 
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This scenario shows the growth of a single file on an otherwise empty 
volume. The process is a bit more confusing when several fiies are 
growing (or being deleted) simultaneously. However, the block allocation 
scheme is always the same: when a new blocl< is needed, SOS always 
allocates the first unused block in the voiume bit map. 



5.3.2 Seedling Files 

A seedling file is a standard file that contains no more than 512 data bytes 
($0 <- EOF < - $200). This file is stored as one block on the volume, and 
this data block is the file's key block. 

One block is always allocated for a seedling file, even if no data 
have been written to the file. 




The structure of such a seedling file looks like this (Figure 5-8): 



K€y_ pointer 

$0 < EOF < 





dala 


Data Block 


S2D0 


block 


512 bytes long 



Figure 5-8. Structure of a Seedling File 

The file is called a seedling file because, if more than 51 2 data bytes are 
written to it, it grows into a sapling file, and thence into a tree file. 

The storage^type field of an entry that points to a seedling file has the 
value $1. 



5,3. 3 Sapling Files 

A sapling file (see Figure 5-9) is a standard file that contains more than 
512 and no more than 128K bytes ($200 < EOF<= $20000). A sapling file 
comprises an index block and 1 to 256 data blocks. The index block 
contains the block addresses of the data blocks. 
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key_ pointer - 





soo'sol' '$fe'$ff 


£$20000 


index block 

1 1 1 I 



InOex Block: 
up to 256 2-byte 
pointers to data blocks 



data 
block $00 



data 




data 


block $01 




block $FE 



data 
block $FF 



Figure S-9. Structure of a Sapling File 



The key block of a sapling file is its index block. SOS retrieves data blocks 
in thie file by first retrieving their addresses in the index block 

The storage_lype field of an entry that points to a sapling file has the 
value $2. 



5.3.4 Tree Files 



A tree file (see Figure 5-10) contains more than 128K bytes, and less than 
1 6M bytes ($20000 < EOF < $1000000). A tree file consists of a master 
index block, 1 to 1 28 subindex blocks, and 1 to 32,768 data blocks. The 
master index block contains the addresses of the subindex blocks, and 
each subindex block contains the addresses of up to 256 data blocks. 



key_pointer 



$20000 < EOF< $1000000 



,$00 ' $01 1 'I7EI$7F 

master index block 
I I I 1 



Master Index Block: 
up 10 128 2-byte pointers 
to index blocks. 



/ 







$00i$0li '$FE'$FF 

index block $00 
1 1 1 1 




S00 1 $01 1 1 SFE ' SFF 

index block $7F 
1 1 1 1 





/ / 



/ 



data 




data 




data 




data 


block $00 


* • ■ * 


block $FF 




block £00 


■ ■ * « 


block SFF 



Figure 5-10. The Structure of a Tree File 
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The key block of a tree file is the master index block. By looking at the 
master index block, SOS can find the addresses of all the subindex 
blocks; by looking at those blocks, it can find the addresses of all the 
data blocks. 

The storage_type field of an entry that points to a tree file has the value $3. 

5.3.5 Sparse Files 

A sparse file is a sapling or tree file in which the number of data bytes that 
can be read from the file exceeds the number of bytes physically stored in 
the data blocks allocated to the file. SOS implements sparse files by 
allocating only those data blocks that have had data written to them, as 
well as the index blocks needed to point to them. 

For example, we can define a file whose EOF is 16K, that uses only three 
blocks on the volume, and that has only four bytes of data written to it. 
Create a file with an EOF of $0. SOS allocates only the key block (a data 
block} for a seedling file, and fills it with null characters (ASCI I $00). 

Set the EOF and mark to position $0565, and write four bytes. SOS 
calculates that position $0565 is byte $0165 ($0564 - $0200 * 2) of the 
third block (block $2) of the file. It then allocates an index block, stores 
the address of the current data block in position of the index block, 
allocates another data block, stores the address of that data btock in 
position 2 of the index block, and stores the data in bytes $0165 through 
$0168 of that data block. The EOF is $0569. 

Set the EOF to $4000 and close the file. You have a 16K file that takes 
up three blocks of space on the volume; two data blocks and an index 
block. You can read 16384 bytes of data from the file, but all the bytes 
before $0565 and after $0568 are nulls. Figure 5-1 1 shows how the file 
is organized: 
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key_polnter 

012 

Key Block 



Data 
Bfocks 




bytes $565 ,$568 



Figure 5-11. A Sparse File 

Thus SOS allocates volume space only for those blocks in a file that 
actually contain data. For tree files, the situation is similar; if none of the 
256 data blocks assigned to an index block in a tree file have been 
aDocated, the index block itself is not allocated. 



On the other hand, if you CREATE a file with an EOF of $4000 (making it 
16K bytes, or 32 blocks, long), SOS allocates an index block and 32 data 
blocks for a sapling file, and fills the data blocks with nulls. 

The first data block of a standard file, be it a seedling, sapling, or 
tree file, is always allocated. 




If you read a sparse file, then write it, the copy will not be sparse: 
all the phantom blocks will be written out as blocks full of nulls. 
The Apple III System Utilities program, on the other hand, can 
distinguish between sparse files and non-sparse files and make a 
sparse copy of a sparse file. Backup III also handles sparse files 
correctly, but it should not be used to make copies, because 
when it backs up a file, it clears the file's backup bit, so that a 
backup of all modified files will overlook the sparse file. 



5.3.6 Locating a Byte in a Standard File 

The mark is a three-byte pointer that is nornnally used to specify a logical 
byte position within a standard file, using the standard model of a block 
file. It can also be used to pinpoint the block number and byte number 



Pile Organizatjon on Block Devices 



99 



within that bloclc where that byte can be found on a volume. To do so, the 
mark is divided into three fields, shown in Figure 5-12: 



Bit 23 it t^f 

T — I — I — I — I — r 
mark indeitblock 

-I I I 1 i L 



8 , 7 



-I — m — 1 — I — r 
data block 



~> — I — 1 — I — I — 1 — r 
byte 



Used by 



Tree only 



Tree, sapling 



All three 



Figure 5-12. Formal of mark 

indexblock {7 bits): 

If the file is a tree file, this field tells which subindex block points to the 
data block- If / = iftdex_block, the low byte of the subindex block address 
is at byte / of the master index block; the high byte is at byte (/+$100). 



data block (8 bits): 

If the file is a tree file or a sapling file, this field tells which data block is 
pointed toby the selected indexblock. lf/ = data_block, the low byte of the 
data block address is at byte / of the index block; tl^e high byte is at byte 
(/■ + $100). 



byte {9 bits); 

For tree, sapling, and seedling files, this field tells the absolute position of 
the byte within the selected data block. 

This format for mark applies to SOS 1 .2, Future versions of SOS 
may use indexing schemes that divide the 24 bits differently If an 
Interpreter uses mark as a three- byte pointer to a logical byte 
position in a file, it will be unaffected by such changes: if it 
meddles with index blocks, it may faii catastrophicaliy trashing 
your disk in the process, under some future version of SOS. 



5.4 Chapter Overview 



The following figures summarize the information in this chapter 

• Figure 5-13. Disk Organization, shows disk layout and directory 
structure, 

• Figure 5-14, Header and Entry Fields, explains the individual 
fields in the preceding figure. 
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Figure 5-13. Disk Organization 
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Figure 5-14. Header and Entry Fields 
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6. 1 Interrupts and Events 



An interrupt is a signal from a peripheral device to the CPU. When the 
CPU receives an interrupt, it transfers control to SOS. which saves the 
current state of the executing program and calls an interrupt handler, 
located in the driver of the interrupting device. After the interrupt is 
handled, control is returned to the program that was interrupted. 

Interrupts allow device drivers to operate their devices asynchronously. 
By using interrupts, a device can operate more efficiently and allow the 
interpreter to continue running while a long I/O operation is in progress. 
For example, when you send a long buffer of text to the .PRINTER driver, 
the driver does not process the text all at once; instead, it immediately 
returns control to the interpreter, and the interpreter can do something 
else while the interrupt-driven .PRINTER driver processes the buffer 
for output. 

The Apple Ill/SOS system fully supports interrupts from any internal or 
external peripheral device capabie of generating them. To use the system 
efficiently, an interpreter must be designed to work properly even if 
interrupted. Thus, the interpreter cannot contain any time-dependent 
code {such as timing loops), except to provide a guaranteed 
minimum time. 

Interrupts are discussed rn detail in the Apple III SOS Device Driver 
Writer's Guide. 

Interrupts are ranked in priority by the priorities of the devices on which 
they occur Each device has a unique priority, assigned at system 
configuration time. In addition, when an interrupt occurs on a device, all 
further Interrupts from that device are locked out until that interrupt has 
been fully processed. For these reasons, SOS never has to deal 
simultaneously with two interrupts of equal priority. Conflicts between 
interrupts of different priorities are resolved in favor of the higher priority: 
a higher-priority interrupt can suspend processing of a lower-priority 
interrupt, but not vice versa. 
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SOS also supports the detection and handling of events. An event is a 
signal from a device driver to an interpreter that something of interest to 
the interpreter has happened. When an event of sufficient phority occurs, 
SOS suspends the interpreter and saves its state, then calls an event 
handler to process the event, then returns control to the portion of the 
interpreter that was suspended. By using events, an interpreter can 
respond to outside occurrences without spending all its time watching 
out for them. 

The most common kind of event is triggered by a software response to a 
hardware interrupt: a device driver (such as the .CONSOLE driver) defines 
a certain occurrence (such as a press of the space bar) as an event, and 
allows interpreters or assembly-language modules to respond to that 
event. In principle, however, events need not be triggered by interrupts; an 
event can signal, for example, an overflow on a communication card, a 
"message received" condition on a network interface, or a "new volume 
mounted" condition on a mass-storage device. Any occurrence or 
condition a driver can detect can be signaled as an event. 

SOS currently supports two events, both detected by the 
CONSOLE driver the Any-Key Event and tfie Attention 
Event. Both of tfiese are produced by interrupts from the 
keyboard. These events are described in the Apple III Standard 
Device Drivers Manual. Additional events may be defined 
by a device driver: for details, see the Apple III SOS Device Driver 
Writer's Guide. 

The most common event sequence is illustrated below. An event is 
armed when the interpreter prepares a device driver to signal a certain 
occurrence (in this case, a keypress) as an event The interpreter supplies 
the address of a subroutine to be called v/hen the expected event occurs. 

When the device driver detects the event (in this case, by means of an 
interrupt), the driver places the event into a queue and returns to the 
interrupted process, whether interpreter or SOS. This is illustrated by 
Figure 6-T 
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Figure 6-1. Queuing An Event 

Any titne SOS is ready to return control to the interpreter, such as after 
executing a call or processing an interrupt, it checks the event queue. If 
it finds an event of a priority above the preset event fence (see Figure 6-2), 
SOS calls an event-handler subroutine within the interpreter When the 
event has been processed, SOS returns control to the main body of the 
interpreter. 
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Figure 6-2. Handling An Event: Case A 
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If SOS finds no event above the fence (see Figure 6-3), the event remains 
queued until the fence is set (by a SET_FENCE call) below the event's 
priority. Then, the event will be processed as soon as the call is 
completed. 



case B; prtonty < fence 
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Figure 6-3. Handling An Event: Case B 

An event need not be triggered by an interrupt: it can occur 
as a result of any operation w/ithin a device driver. But events are 
detected only by device drivers, and are handled only by an 
event- handler subroutine within an Interpreter An event handler 
will be called only after a SOS call or an interrupt is processed. 



6.1.1 A rming an d Disarming Events 



SOS has not defined a uniform mechanism for arming and disarming 
events: this Is left up to the device driver that supports the event. The two 
existing events are armed and disarmed by D_CONTROL calls to the 
.CONSOLE driver 

An interpreter arms an event by passing three items to the device driver: 
the address of the event handler, a one-byte event identifier (ID), and a 
one-byte event priority. The event ID indicates the nature of the event, and 
allows the event handler to distinguish different events. For example, the 
event ID for the Any-Key Event is 1 ; the event ID for the Attention Event Is 
2. The event priority Indicates the importance of the event, and determines 
when, or whether, the event will be processed. 

An interpreter disarms an event by arming it with a priority of zero: this 
ensures that it will be ignored. 

6. 1.2 The Event Queue 

More than one event can be armed at once, and more than one event can 
occur during a driver's operation. SOS has a priority-queue scheme for 
keeping simultaneous events In order. 

When a driver detects an event, it assigns an ID, a priority, and an event- 
handler address to the event. (These are the values the interpreter passed 
to the driver when the event was armed.) The ID, priority, and address are 
placed in an event queue (see Figure 6-4) maintained by SOS, 
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Figure 6-4. The Event Queue 

The queue is arranged in order by priority: an event of liiglier priority will 
be handled first. The highest priohty is $FF: this pnortty guarantees that 
an event will be handled before any other event. Events of equal pnority 
are queued first-in, first-out (FIFO): an event with the same priority as 
another event already in the queue is placed after the other event. Events 
of priority $00 can never be handied, so they are not queued. 



6.7.3 The Event Fence 

The priority ordering of the event queue determines not only when an 
event will be handled, but also whether it will be handled at all. SOS 
maintains an event fence (see Figure 6-5) that determines which events 
will be processed and which will not. 

The fence is a value from $00 to $FF that is compared to the pnority value 
of each event in the queue. Only those events whose priority is greater 
than the fence will be handled; setting the fence to $FF ensures that no 
events will be handled. 
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Figure 6-5, The Event Fence 

All events above the fence are handled, in order, and removed fronn the 
queue before SOS returns control to the suspended portion of the 
interpreter Events below the fence remain in the queue, and may be 
handled when the fence is lowered. 



Two SOS calls, SET_FENCE and GET_FENCE, allow an interpreter to set 
and read the value of the fence. If the interpreter lowers the fence while 
events are in the queue, previously queued events whose priority values 
are greater than or equal to the new value of the fence will be handled 
immediately after the call is completed. 



6.1 A Event Handlers 

An event handler is a subroutine in the interpreter that is called by SOS in 
response to an event, under certain conditions. An event can only be 
processed when the interpreter is executing. If a SOS call is being 
executed when an event occurs, the event is queued; after the call is 
executed. SOS will call the interpreter's event handler if the event's priority 
is higher than the event fence. When the event handler is called, the 
previous state of the machine is stored on the interpreter's stack, and the 
event ID byte is stored in the accumulator; then the event is deleted from 
the queue. 
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Among the items saved on the stack is the current value of the event 
fence. The fence is then raised to the level of the current event until the 
event has been processed; this ensures that no event of lower priority will 
preempt the current event, now that the current event is no longer in the 
queue. Figure 6-6 illustrates the system status during event handling. 



event id 







's * 




S ^ 1 


fence 


S + 3 


SOS 
return 
address 


S + 4 









PHA 
PLA 



Figure 6-6. System Status during Event Handling 

The event handler uses the event ID to determine the reason it was called 
and to take appropriate action. 

When the event handler is finished, it returns control to SOS via an RTS; 
SOS then restores the system to its previous state, and returns control to 
the suspended portion of the interpreter Since the previous state included 
the event fence, any fence set by the event handler will be lost, unless that 
fence value is passed to the body of the interpreter and reestablished 
by it. 
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6.1.5 Summary of Interrupts and Events 

• Interrupts are generated by hardware; events are generated by 
software. 

• Interrupts are ranked by the priorities assigned to the devices 
they occur on; events are ranked by the priorities assigned to 
them by the drivers that detect them, 

• Interrupts are stacked; events are queued. 

• Interrupts are handled by an interrupt handler in a device driver 
events are detected and queued by a device driver, and 
processed by an event handler in the interpreter 

• Interrupts can preempt the interpreter or SOS; events can only 
preempt the interpreter. 

• Interrupts cannot be disabled by the interpreter; events can be 
disabled by setting the event fence to $FF. 

6.2 Resources 



The Apple HI has two resources accessible by special SOS calls: the 
system clock and the analog ports. 

6.2.7 The Clock 

The Apple III system clock runs continuously; when the computer is 
turned off, the clock runs on batteries. It keeps time down to the 
millisecond, and can be read and set by SOS. 

The clock is set and read by two calls: SET_TIME and GET_TIME. To set 
the time, the calling program writes it as an ASCII string into an 1 8-byte 
buffer in memory, then passes SOS the address of the buffer: SOS then 
sets the clock to the specified time. To read the time, the calling program 
passes SOS the address of an 1 8-byte buffer: SOS then writes the current 
time into this buffer. 
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If the computer has no functioning clock, SOS responds to a SET TIME 

call by saving tfie time it receives. SOS returns this time unchanged upon 
a subsequent GET_TIME call. 

Both calls express the time as an 1 8-byte ASCII sthng of the following 
format: 

VYYYMMDDWHHNNSSUUU 
The meaning of each field is as below: 



Field 


Meaning 


Minimum 


Maximum 


YYYY: 


Year 


1900 


1999 


MM: 


Month 


00 


12 December 


DD: 


Date 


00 or 01 


28, 30, or 31 


W: 


Day 


01 Sunday 


07 Saturday 


HH: 


Hour 


00 Midnight 


23 11:00 p.m. 


NN: 


Minute 


00 


59 


SS: 


Second 


m 


59 


UUU: 


Millisecond 


000 


999 



For example, Monday, December 29, 1980, at9:30a.m- would be specified 
by the string "198012290093000000'\ 

On input, SOS replaces the first two digits of the year with "19" and 
ignores the day of the week and the millisecond. SOS calculates the day 
from the year, month, and date. 

SOS does not check the validity of the input data. The clock rejects any 
invalid combination of month and date, February 29 is always rejected. 

The clock does not roll over the year. 
6.2.2 The Analog Inputs 

The GET_ANALOG call reads the analog and digital inputs from an 
Apple 111 Joystick connected to port A or Bon the back of the Apple III. It 
can also read compatible signals from other devices. 
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6.2.3 TERMINATE 

The TERMINATE call provides a clean exit from an interpreter. 
It clears memory, clears the screen, and displays the message INSERT 
SYSTEM DISKETTE AND REBOOT on the screen. The TERMINATE call 
is useful as part of a protection scheme that locks out the NMI. Such a 
scheme allows only one way of leaving the program, and erases it 
completely afterward. 

Before using this call, an interpreter must close all open files. This 
V y will ensure that no halt-written buffers are left in limbo. 



6.3 Utility Calls 



These calls deal with the system clock/calendar, the event fence, the 
analog input ports, and other general system resources. The name of 
each call below is followed by its parameters {in boldface). The input 
parameters are directly-passed values and pointers to tables. The output 
parameters are all directly-passed results. The SOS call mechanism is 
explained in Chapters; the individual calls are described fully in Chapters 
9 through 12 of Volume 2. 

SET_FENCE 
fence: value 

This call changes the current value of the user event fence to the value 
specified in the (ence parameter. Events with priority less than or equal to 
the fence will not be serviced until the fence is lowered. 

GET_FENCE 
lence: result 

This call returns the current value of the user event fence. 
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SET_TIME 
time: pointer 

This call sets the current date and time. SET_TIME attempts to set the 
hardware clock whether it is operational or not. It also stores the new time 
in system RAM as the last known valid time: this time will be returned by 
all subsequent GET_TIME calls if the hardware clock is at>sent or 
malfunctioning. 

GET_TIME 
lime: pointer 

This call returns the current date and time from the system clock. If the 
clock is not operating, it returns the last known valid date and time from 
system RAM. If the system knows no last valid time, GET__TIME returns a 
string of 18 ASCII zeros. 

GET_AMALOG 

joy mode: value; joy status: result 

This call reads the analog and digital inputs from an Apple III Joystick 
connected to port A or B on the back of the Apple III. 

TERMINATE 

This call zeros out memory, clears the screen, displays INSERT SYSTEM 
DISKETTE & REBOOT in 40-column black-and-white text mode on the 
screen, and hangs, until the user presses CONTROL-RESET to reboot the 
system. This call uses no parameters. 
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This chapter describes the two kinds of assembly-language programs that 
you can use: interpreters and modules. It discusses their structures, 
operating environments, and special characteristics; it explains how to 
create them and how to get them successfully loaded into the system. 

7.1 Interpreters 



The interpreter is the assembiy-language program that SOS loads into 
memory from the file SOS.INTERP and executes at boot time. The 
interpreter can be a stand-ator^e Interpreter, like Apple Writer 111, or it can 
be a language interpreter, like the BASIC and Pascal interpreters. A 
stand-alone interpreter, normally an application program, provides the 
interface between you and SOS. A language interpreter can either provide 
this interface directly, as does BASIC, or support a program that does, as 
does Pascal, or both. A language interpreter can load and run your 
program in response to your command, or it can load and run a greeting 
program at boot time. 

The interpreter is stored in its entirety in the file SOS.INTERP in the 
volume directory of the boot diskette. Additional functions can be added 
to the interpreter by use of assembly-language modules (see section 7.4). 

An interpreter can 

• Make SOS calls; 

• Store and retrieve information in memory; and 

• Handle events. 

The SOS calls made by an interpreter can interact with you through 
devices, store or retrieve data, or request memory segments in which to 
store data. The memory accesses made by an interpreter can manipulate 
any information in the memory segments owned by the interpreter. The 
events handled by the interpreter can let it respond to special 
circumstances detected by device drivers. 
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7.1.1 Struc ture of an Interpreter 

An interpreter is stored in a file named SOS.tNTERP in the volume 
directory of a boot diskette. The data in this file consists of two parts: 
a header and a part containing code — as shown in Figure 7-1, 



abyles 



label 



2by1e3 



(ipl_header_lenglh = m 



m bytes j 



opt header 



header 
part 



2 bytes 



loading address 



2 bytes 



code Jen glh = n 



f) bytes K 



code part 



/ 



Figure 7-1. Structure of an Interpreter 
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The header consists of five fields, described below: 
label (8 bytes): 

Ttiis field contains eight characters 
SOS NTRP 

including the space. This is a label that identifies this file as an interpreter. 
The letters are all uppercase ASCII with their high bits cleared. 

opt_header_ length (2 bytes): 

The next field contains the length of an optional header information 
block: if no optional header block is supplied, these bytes should 
be set to $0000. The length does not include the two bytes of the 
opt_header_ length field itself 

opt header (opt header length bytes): 

If the previous field is nonzero, the optional header block comes here, 
loadlngaddress (2 bytes): 

This field is the loading address (in current-bank notation) of the code 
part that must go into the highest bank of the system. 

code length (2 bytes): 

This field is the length in bytes of the code part, excluding the header. 

For example, an interpreter that begins at location $9250 in the highest 
bank of the system, is $25AF bytes long, and has no optional header 
would have a header part like this; 



.WORD 00W 
.WORD 9250 
.WORD 25AF 



-ASCII 



"SOS NTRP' 



; labetforSOS INTERP 
; opt_header_length - 
: loading .address 
: code_lengtli 




Interpreters are always absolute code, and must start at a fixed 
location. A program in relocatable format cannot be used as an 
interpreter 
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The header is immediately followed by the code part of the interpreter. 
During a system bootstrap operation, the code part is placed at the 
address given in the header, so that the first byte of code resides in the 
location specified by loading_address (location $2:9250 for the above 
example, in a 128K system). When loading is completed, execution 
of the interpreter begins at this location: the header part is discarded. 

SOS requires only that the first byte of the code pari be executable 
interpreter code; the rest of the code part of the interpreter may 
be in any format. 

7. 7.2 Obtaining Free Memory 

An interpreter can use any and all memory that is not already allocated 
to SOS or device drivers, but first it must request this memor/ from SOS. 
The REQUEST_SEG and FIND_SEG calls to SOS can be used by an 
interpreter to request an area of memory in which to store data. 

By allocating a segment of memory for its exclusive use, the interpreter 
ensures that no other code— the SOS file system, a device driver, an 
invocable module — will use ttiat segment for another purpose. SOS 
allocates by an honor system: it protects allocated memory from conflict, 
but cannot prevent the use of unallocated memory. You can avoid 
memory conflict entirely by always allocating memory before use and 
deallocating it after use. 



( nl J } Using unallocated rriertiory cari have dramatic results. When an 
^is=^ interpreter overwrites a file's I/O buffer, the system crashes. ]t 

does so to avoid trashing a disk: since the buffer contains block- 
allocation information as well as the interpreter's data, SOS would 
compromise the entire disk if it wrote out a buffer altered by the 
interpreter To avoid this, SOS comes down with a SYSTEM 
FAILURE 16 message. When this happens, the data in I he I/O 
buffer, as well as the data in memory, are lost. 

The piece of interpreter code given below uses the FINO__SEG call 
{described in Chapter 1 2 of Volume 2) and the segmenWo-extended 
address conversion described in section 2.2.3.1 , It requests a 1 K segment 
of memory {consisting of four adjacent memory pages) and fills that 
segment with zeros. 
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The first part of this procedure is the call to SOS to find a segment of the 
appropriate size. This is done with a FIND_SEG call. 



FINDSEG 


EQU 


041 




rINUl 1 


now 




Penorm tne bUb call 




.Dl 1 t 




, rINU bt^ 






CC DA □ A K/tC 


; with the fsquifsd param^lgrs hst's. 








t IF successful, THEN process addressss. 




LAJf\ 




; ELSE 588 how b(g it c^n b6. 






rlrJUl 1 


; IF any free memory exists, THEN ask agairt 




JMr 


trtnUnriAL 1 


i ELSE stop 6X6C u t ion . 


FSPARAMS 










BYTE 


06 


; Six parameters tor FIND_SEGt 


SRCHMOD 


BYTE 


00 


; Seg must be in one bank 


SEGfD 


BYTE 


11 


; (11 call it seg. 11. 


PAGES 


WORD 


04 


; Ask for 1K of memory 


BASE 


WORD 


0000 


; "base" result parameter 


LIMIT 


.WORD 


0000 


; "limit" result parameter 


SeGNUM 


BYTE 


00 


; "seg.num" result parameter 


EXUIMIT 






; Place to store (extended form of) 




.WORD 


00 


; limit bank and page. 



Once the FIND_SEG call succeeds, the values at BASE and LIMIT contain 
addresses in segment-address form of the first and last pages in the 
segment. Now the base and limit addresses must be converted into 
extended form to be used in clearing the memory in that segment. The 
first part of this process is determining where the segment is located; in 
the S-bank, in bank 0, or in another bank in bank-switched memory. 



CONVERT LDA BASE ; Get bank number of segment 

BEQ SZBANK ; Is it in bank 07 

CMP #0F : is it in low S-bank? 

BEQ SZBANK 

CMP #10 [s it in high S-bank? 

BEQ SZBANK 



For the general case (any bank butS or0), the conversion involves 
calculating the proper X-byte and creating the two-byte address 
for the pointer. 
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ANYBANK 



CLC 




Turn bank numbsr into X-byte 


ADC 


#7F 


XX = $80 t bb - 1 


STA 


1651 


Store it in X-page for pointer. 


LDA 


BASE + 1 


Get page number in bank 


CLC 




Turn into high part of address 


ADC 


W60 


NNNN .= pp00 f $6000 


STA 


51 


Store into zero-page pointer 


LDA 


tfM 


Create low part of S00 


STA 


50 


Store into zero-page pointer 


LDA 


LIMIT 


Get bank number of segment, 


CLC 




Turn into X-byte 


ADC 


#7F 


XX = $80 + bb - 1 


STA 


EXTLIMIT 


Store it in X-page lor pointer. 


LDA 


LIMIT + 1 


Get page number of limit. 


CLC 




Turn into extended form for 


ADC 


#60 


later comparison with page 


STA 


EXTLIMIT + 1 


being zeroed, 


JMP 


CLEARIT 


and proceed to clear the segment 



For the case where the segment resides in bank or the S-bank, the 
conversion is much easier: just use an X-byte of $8Fand create the proper 
two-byte address. 



SZBANK 



LDA 


#8F 


; LJse an X-byte of S8F 


STA 


1651 




LDA 


BASE + 1 


; Get page number in tiank 


STA 


51 




LDA 


#00 


; Create low part of $00 


STA 


50 




LDA 


#8F 


; Use limit X-byle of $8F 


STA 


EXTLIMIT 




LOA 


LIMIT + 1 


; Convert page number of limit 


STA 


EXTLIMIT + 1 


: to extended form. 



Now an extended pointer has been created and is stored in locations 
$0050, $0051, and $1651 -This pointer indicates the beginning of the 
memory range allocated by SOS in the FtND_SEG call. 



A process similar to the above can be used to convert the limit segment 
address into another extended pointer to define the end of the segment. 



Remember that the limit address specifies the last page in the 
segment. Converting the limit address into a pointer using the 
method shown above will give you a pointer to the lieginning of 
this page, not the end. Keep this in mind when comparing two 
pointers derived from base and limit segment addresses. 
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Once the pointers are set up, a simpler form of the increment loop 
described in section 2.4.2,1 can be used to scan through every location 
in the segment and, in this example, set each byte to $00. Because the 

FIND SEG call requested that the entire segment reside in one bank, 

the increment loop does not need to increment the X-byte of the pointer, 
or compare the base X-byte to the limit X-byte. 



LDY 


m 


; Use Y as an index in each page. 


IDA 


m 


; Value to pgl in each location. 


STA 


(50),Y 


; Extended-address operation. 


INV 




; Do next byte in page. 


BNE 


STORE 




INC 


51 


; Move to next page. 


LDA 


51 


: Get tiigh part of address. 


CMP 


EXTLIMIT + 1 


; Compare with high part □( linnit. 


BOG 


STORE 


; If pointerhigh < = limit. high. 


BEQ 


STORE 


; clear another page. 



A program that wishes to use more than 32K bytes of memory must 
handle the incrementing and comparing of X-bytes in a loop like this: 



STORE 



CHECK 



LDY 


m 


; Use Y as an index in each page 


LDA 


#0 


; Value to put in each location. 


STA 


(50).Y 


; Extended-address operation. 


INY 




; Do next byte in page 


BNE 


STORE 




INC 


51 


; Move to next page 


BNE 


CHECK 


; If same banl<. checK limit 


LDA 


Mats 


else 


STA 


51 


; set page to $80 


INC 


1651 


• and increment X-byte 


LDA 


1651 


; Compare X-byte to 


CMP 


EXTLIMIT 


; limit X-byte 


BCC 


STORE 


: If less than, clear page 


LDA 


51 


; else compare page 


CMP 


EXTLIMIT + 1 


; to limit page 


BCC 


STORE 


; If less than 


BEQ 


STORE 


: or equal, clear page 
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Z1.3 Even t Arming an d Response 

To arm an event, an interpreter may pass the starting address of its event 
liandler to a device driver that can detect the event. When the event 
occurs, the interpreter's event handler will be called. One way to arm an 
event is by a D CONTROL call to a device driver. 

For example, assume that the -CONSOLE device driver defines a certain 
keypress as an event. An interpreter that wishes to use this feature would 
include a subroutine that is to be called each time that key is pressed. The 
interpreter would make a D_CONTROL call to the CONSOLE driver, 
passing it the ASCII code of the keypress to detect and the address of the 
event handler When the key is pressed, the console queues the event 
handler's address, and SOS calls the event handler to handle the 
keypress. 

The D_CONTROL calls that arm an event for a given device driver are 
described in the documentation accompanying that driver. For the 
.CONSOLE events, see the Apple lit Standard Device Drivers Manual. 



7.2 A Sample Interpreter 

This section illustrates the design and construction of a very simple 
interpreter The example is simple, but has all the parts an interpreter 
must have. It shows how SOS calls are made (see Chapter 8 for a full 
explanation), and how events are handled. The complete listing of the 
interpreter is shown in the next section; in this section we explain 
portions in detail. 



This model is intended for demonstration only It does not luHy 
show all features of SOS (sucfi as memory a I local ion ] aval I able to 
an interpreter, nor does it contain comprehensive error-checking 
and debugging aids. Use this model only to gain insight into the 
construction of an interpreter; please do not base your own 
designs upon it 



This program, SCREENWRITER, reads a byte from the keyboard, then 
writes it out to the screen, without filtering out control characters. It writes 
explicitly, without using screen echo. 
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The interpreter contains an event mechanism. When CONTROL-Q is 
read, the console driver detects it as an event. The event is processed 
v/hen control next returns to the interpreter If the character typed before 
the CONTROL-Q is ESC, the event handler beeps thrice and issues a 
TERMINATE call; if not, the event handler just beeps thrice. 

This interpreter is deliberately inconsistent in style, in order to show 
different ways of coding SOS calls. Some calls are coded in line; some, 
as subroutines. Some are coded with a macro, SOS; some are not. The 
macro itself can use the SOS call number, or the number can be given 
the name of the call, via an .EOUate statement. 

The syntax for a SOS call using the SOS macro is 

SOS call num, parameter list pointer 
For example, the call 

SOS READ, READLIST 

uses the label READ, w/hich has been defined as $CA by an .EQUate. This 
call could also have been coded as 

SOS OCA, READLIST 

READLIST is a pointer to the required parameter list. In this sample 
interpreter, the required iist precedes the call, as the Apple III Pascal 
Assembler accepts backw^ard references more readily than forward 
references. 

Here is the macro definition for a SOS call block: 



.MACRO 
BRK 



SOS 



: Macro det for SOS call block 
; Begin SOS call block 
: calLnuffl 

; parameter, list pointer 
; end ot macro definition 



BYTE 

•WORD 

-ENDM 



%1 
%2 
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After the header and parameter lists for various calls (shown in the 
complete listing, but not in this section), comes the main interpreter 
program, which is in two sections. The first section, the initialization 
block, opens the console and gets its dev_num: turns off screen echo 
passes its ref_num and dev_num to subroutines; arms the attention 
event; and sets the fence. 



BEGIN 



.EQU 

JSH 

JSH 

JSR 

JSR 

SOS 



LDA 
STA 
STA 



OPENCONS 
GETDNUM 
SETCONS 
ARMCTRLO 
60. FENLIST 



REF 

RREF 

WREF 



Open CONSOLE 
Get dev_num 
Disable echo 
Arm attention event 
Set event tenoe to 0. 
here we coded "60" directly 

Set Ltp ref_num 
for reads 
and writes 



The main program loop uses a two byte I/O buffer, the second byte of 
which is always a line feed (LF). The main program reads a byte from the 
keyboard into the first byte of the I/O buffer, then checks whether that 
byte is a carriage return (CR): if so, both bytes in the buffer will be written; 
if not, only the first byte will be written. This is done by setting the value of 
the write count {WONT in the listing, or bytes in the call definition) to 2 or 
1, respectivety. The loop repeats indefinitely; the only exit from the 
program is through the event-handler subroutine, HANDLER. 

The numbers preceded by a dollar sign, like $010, are local labels. The 
numbers are decimal, not hex. 



SOS 


READ. RCLIST 


; Read In one byte: 






: here we used READ for 0CA 


LDA 


RCNT 


; IF no bytes were read 


BEQ 


$010 


; THEN go read again 


STA 


WONT 


: Set up write count 


LDA 


BUFFER 




CMP 


#0D 


; IF first byte in buffer is CR 


BNE 


$020 


; THEN write out LF also 


INC 


WONT 




SOS 


WRITE, WPLIST 


; Write out 1 or 2 bytes 


JMP 


$010 


; Repeat ad infinitum 
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The first subroutine is OPENCONS. which opens the .CONSOLE file for 
reading and writing. It consists of a single SOS OPEN call, and is coded 
with the parameter lists preceding the call block, which here is coded 
without a macro. 



CODST 
CREF 

COPLIST 
OPENCOMS 



.BYTE 04 
.WORD CNAME 



.BYTE 



.BYTE 



.BYTE 



m 



.WORD COPLIST 



01 



03 



BRK 

.BYTE 0C8 
.WORD COLIST 



CREF 
REF 



4 required parameters for OPEN 
pathname pointer 
ref_num returned here 
option_lisi pointer 
length of opt parm list 

Open for reading and writing 



Here we didn't use a macro 
Begin SOS call block 
Open the console. 
Pointer !o parameter list 
Save the result ref_num 
for READS and WRITES. 



The next subroutine, GETDNUM, which returns the dev num of 
.CONSOLE, is coded similarly, except that it has no optional 
parameter list. 



The SETCONS subroutine suppresses screen echo on the .CONSOLE 
file. This is a very simple example of a D_CONTROL call, as the control 
list is only one byte long; the next is more complex. 



SETLtST 
CNUM 



.BYTE 
BYTE 
BYTE 



03 
00 

m 



.WORD CONLIST 



CONLIST 



BYTE FALSE 



3 required parms for DECONTROL 
dev_num of .CONSOLE 
controLcode = 03: screen echo 
control_list pointer 



Disable screen echo 



SETCONS 

LDA CONSNUM ; Set up device number 

,gTf»- CNUM ; of .CONSOLE 

•00^ D__CNTL, SETLIST 
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The ARMCTRLQ subroutine arms the Attention Event for CONTROL-Q. 

The D CONTROL call in this subroutine sends the evert priority, event 

ID, event-handler address, and the attention character code to the 
.CONSOLE driver 



DCLIST 
DNUM 



.BYTE 

-byte 

BYTE 



03 



.WORD CLIST 



Srequtred parms for DECONTROL 
dev.nurm of .CONSOLE goes here 
control _code = 0S: 

Arm Aiiention Event 
conlroM'St pointer 



CLIST 



BANK 



BYTE 

.BYTE 

.WORD 

BYTE 

.BYTE 



0FF 

02 

HANDLER 

00 

11 



Control list 
Event priority 
Event ID 

Event handler address 
Event fiandlerbank 
Attention Character = CTRL-Q 



ARMCTRLO 



LDA 
STA 
LDA 
STA 
SOS 
RTS 



BREG 
BANK 
CONSNUM 
DNUM 

D_CNTL, DCLIST 



Set up bank number 

of event handler 
Set up device number 
for control request 
D_CONTROL call macro 



The next subroutine, HANDLER, is the attention event handler. It reads 
the attention character (CONTROL-0) from .CONSOLE, then beeps 
thrice. If the previous character was ESCAPE, the program terminates. 
A buffer separate from the main t/0 buffer is used for reading the attention 
character, as otherwise the attention character would sometimes clobber 
the character in the buffer before it could be written to the screen. 



The buffer BELLS contains three BEL characters, separated by a number 
of SYNC characters. When written to the console, these cause a total 
delay of about 150 ms, HBLK1 and HBLK2 are required parameter fists 
for the READ and WRITE calls. HBUF1 is a one-byte buffer for the 
attention character. 
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BELLS 


EQU 




; Buffer with BELs and delay? 




.BYTE 


07 


; BEL 




.BYTE 


16,16,16.16,16,16,16,16,16 


; SVNCs 




.BYTE 


a? 


; BEL 




.BYTE 


16,16,16,16,16,16,16.16,16 


; SYNCS 




.BYTE 


07 


; BEL 










HBLK1 


BYTE 


04 




HREF1 


.BYTE 


m 


; ref_num 




.WORD 


HBUF1 


; data_buffer pointer 




.WORD 


0001 


; requesl.count 




-WORD 


0000 


transfer_coun1 


HBUF1 


BYTE 





; Buffer for reading attention char 




.OTIC 




, requiicu p drain civrs ror wni i c 


HREF2 


.BYTE 


00 


; ref_num 




.WORD 


BELLS 


; data_t)uffer pointer 




.WORD 


BELLEN 


; fequesLcount 


HBLK3 


.BYTE 


01 


; 1 required parameter for CLOSE 




-BYTE 


00 


; ref.num - 0: CLOSE all files 


HBLK4 


.BYTE 


00 


; required parms forlERMtlMATE 



These data structures are followed by the actual code of the event 
handler. Here the SOS calls are coded using macros. 

HANDLER 



LDft 


REF 


; Set up reference numoers 


STA 


HREF1 


; tor console READ 


STA 


HREF2 


; and console WRITE 


SOS 


READ.HBLKI 


: Read attention character 


SOS 


WRITE, HBLK2 


; Write three BELs to .CONSOLE 


LDA 


BUFFER 




CMP 


#1B 


; IF last keystroke was ESCAPE 


BNE 


$010 




SOS 


0CC, HBLK3 


; THEN CLOSE all files 


SOS 


065,HBLK4 


J and TERtWINATE 



JSR 
RTS 



ARMCTRLQ 



ELSE re-arm attention event 
and resume execution 
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The TERMINATE call could have been coded in the following 
perverse way: 

TERM BRK ; Begin SOS call 

.BYTE 065 ; call.num for TERMINATE 

.WORD TERM ; para meter, list pointer 

Since the TERMINATE call has no parameters, the required parameter list 
need be onfy an ASCII null ($00). Thus TERM, the parameterjist pointer, 
points to the BRK that begins the call. 

A simpler coding, using a macro, is this: 

TERM SOS 065, TERM ; Pointer to BRK 

The following pages contain a complete listing of the program, including 
all subroutines and parameter lists, as well as the code necessary to 
generate a valid header. 



12. 1 Complete Samfyle Listing 



fACE - 

Current semtji-y aveLlabla; Wii06 

0000 ,,\BSOLIJTe 

0000 .NOPftlCHUIST 

0000 .NOWACROLIST 

2 blocks foe procedure co,ie 1 6] 36 wurjs Lefc 
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PACE - 1 SCREENU^ FLLE: 



0000 1 

Currenc sesiorv ^VAiij^blc: 
0000 
0000 
0000 
uocso 

oooo 
onou 

0000 
0000 
0000 

oooo 
0000 
0000 
OOQO 

oooo 
0000 
0000 

0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 

oooo 
0000 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 
oooo 



• PBOc scBEemmiTEn 



Sampic Incerprecec for S6S Reference Manual 
Dan Reed and Thonas ftoDC, II AugiiBC 193?. 



This iirogmn reads tiytes frara che kwybaard, cbtn urltes 
the™ out to ttw jicrtmn^ wfthnuc flltf^ftnfi ouc *;oncrrtl 
characcerA. It wrLt?& mpllcLcLy^ i^Lthouc u£lrg screen 
echo* 

The Interpreter contains an event aeehanlsm^ When 
COSTROL-0 Is re^dt the cansoltf driver deteccs It as an 
e^rent. The event is processed when control next returns 
tn the Interpreter. kf the character typed before the 
CaNTROL^J la Esc, th*-» event handler biitfpE^ the Ire ^nd 
Issues a TERMINATE call; If nnt, the n^vent handler iust 
beepd chrlce* 



Note on ptogrdranlnf styles the style of this ptogran Is 
deliberately inco/ESlstent^ to show several ways to code 
SOS calJa. Thry can he coded In line; they can be coded 
is £ubroutlnefi. They Ciin be coded vUh or without s 
macro, SOS, The nacro Itjtvlf can use tlte SOS call nunber, 
ot it can use the nvine^ vln an .ECU at a. In genera], 
data structures appear before the code using thetti: chis 
U recommended practice uith Che Apple lit ^AScal 
Aiiserahler. 



The source file for the ^icreenwriCuT progranr Is replicated 
83 SCMENURIT.TfKT on the BserSnS disk. 



Aih***** It i^lV****,kih*4******it*lt*l^*** ****** A*a*a ******* 1^*4^ 
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PA51 - 2 SCneENUR flUE; 







.FAC£ 






0000 






**»****^*** *S ** ********** 


0000 










ooco 






Pare of File 




0000 










OQOO 
0000 


















0000 


sooo 




9000 ; 


Code begins at $4000 


0000 




.ORG 


ST^»T-0E ; 


teAV« t2 b^ti-s for hcndi^t 


STf2 








BFF2 


53 IF S3 20 4E M 51 


.ASCII 


"SOS MIW" ; 


Iflbel far SOS^tMTEiy 


8Ff9 


50 










0000 


.UOKD 


0000 ; 


Qpt hesder len^Eh = 


srFC 


0090 


.UORD 


START ; 




8FPE 




.UORO 


COOEIXN ; 


cade length 


9000 










9D00 




JMP 


BeclN ; 


Jump to begLritLng ctjie 


9003 










9003 




****** *********************** 
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- 3 


9003 








9003 




9003 




»UU3 




9001 




9003 




90D} 




9003 




90Q3 




9003 




9003 




9003 




9003 




9O03 




9003 




9003 




9003 




9003 




9003 




9003 




9003 




900 3 




9003 




9003 




9003 




9001 


OOCA 


9003 


OOCfl 


9003 


0063 


9003 




9003 




9003 




9003 




9003 




9003 




9003 




9003 


0000 


9003 


aoso 


9001 




900 3 


FFEF 



3 SCREENWft Fae: 



Hacrus, ^qutttes, And G-lo^X Data Ared 

The fryntax tot d SOS c^U Rising the n^tro below is 

SOS taU_nyin, p3raraecer_i Ut palnc^r 

TtiE macro definition tor SOS CaU bL&ck. using tKe nbpve 
fittmat below: 



.HACRO SOS 
BRK 

.BYTE XI 

. VORO %2 



; a^crc def for SOS cail block 
I BegU SOS call block 
; €9 LI num 

J paramecrer Use potncfcr 
: tnd ot macro definttlon 



Here are .EOUates for call rtums: 



READ >eOLI CCA 
D CNTL .EOU OBa 



! caU^ttum for READ 

S call TiUiP for WRITE 

■ cs.\l~fiim for D CONTROL 



Here are Dore .EQUaHes; 



FALSE ,EOU 00 
TRUE .EOU 80 



BREC .EQU OFFEf 



J Bank realsier 
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PACE - 4 SCREEHUH f(LE: 



9003 
9003 
9003 












* 






9003 






Th«sc variables ^re usee 




»003 




f 


main program an<l rhe OPENCO^TS ^ubroHl In*-. 


M03 
9003 
9003 




i 














900) 






-flYTE Ofl 




9004 


2F- 43 4F iE 53 4F 4C 




-ASCII ".COtlSOlE" 




900 B 


45 








!>00C 


00 




.BYTE 00 




9000 


00 








9i)oe 










900 E 
900E 












; 






SOQE 




f 


Here Lh« buFfef 


for rhc- READ afi*l WRITE i' ilU in 


9flOE 




i' 


the main proRrdtn. 


che first by:e is writTh-n into; 


900 E 






one or both are written 




9006 
900E 
900E 




; 














WOE 


00 0* 


auF PER 


.f\nt 00, OA 


; dar,i lnifii?r with crdlMns \.7 


9010 










9010 
9010 












i 






9010 






Here acs rtq^iireJ pflfniqcC'ifr Hhcs For SOS caIVr in tUf 


9010 






ma In pro^raniT 




9010 










9010 
9010 


















9010 


01 




.am: 01 


; 1 parflfifftMr fat SET f'r.N<:£ 


901 1 


00 




.BYTE 00 




9012 










9012 


04 




.BYTE 04 


;. A pAruiGCcira For RFAU 


9013 


00 


RH£F 


-BYTE 00 




90|i 


0E90 




.WORD BUFFER 


3 <trttfl tniffer ptiint^r 


9016 


0100 




. WOi^ 000 1 


rpqupTiE roiini 


9018 


0000 


RCKT 


.WORD 0000 




90M 










9aiA 


01 


UPLJST 


, BYTE 3 


; 3 (iiiriietn>i:i?r'( for URItK 


901 e 


00 


UR£F 


. B YTE 00 


i ref rmnr {frcnn UPV.fi cflLll 


soic 


0E90 




,yOIU) BUFFER 


; dat.i txilfer p<'^Lni:>i!r 


90 IE 


0000 


UCiJT 


« WR0 0000 


i CL'queaE count 


90 ZO 










9020 
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PAC;E - i SOIEENWS fILE: 



mo 






.PACE 






9070 










90J0 












9020 






i Mb In 


Pro rEPi Code 




90 20 










902U 










:::::;:::::;!::;;:;;:::!;;;;;:;;!:•; 


WiO 












9020 






i This 


i6 Che setup povz 


ion^ exi:'i:»jt:i?(1 the srarL. 


90! 












9020 
90^0 






















90 M 


9020 


BEGIN .SOU 


n 




9020 


20 




JSR 


OPEHCOtiS 


; Opfefi .CONSOLE 


9023 


20 






Cei'DNUM 


; Gee dev num 


9016 


20 




JSR 


SEIKOMS 


; UieaSle echo 


9029 


20 




JSd 


AfiJICTW.0 




90 2C 






SOS 


60, FEKLIST 


; Set eveiu fcnru Di 


9030 










; hece we coded "fjO" dLtencl^y 


9030 










9030 


AO 


0C90 


LDA 


REF 


J Sj5c up rcf fiotit 


9033 


BD 


1390 


StA 


RKEF 




9ttl6 


SD 


1890 


STA 




; And urki^ti 


9039 












9039 
9039 






















9039 






This 


is the Ttatn loop. 


executed lintli cerrelnstlon* 


9039 












9039 
9039 






















9039 






£010 SOS 


READ, flCLLST 


; Raad tn on? byce; 


9030 










; )tKtii iLfK uspd READ f^r OCth 


ma 


AD 


1B90 


LDA 


ROUT 


J LF no bycEs WL-re re^d 


90^0 


F0F7 


6E0 


$010 


; THCM gfl resd s^iln 


9042 












9012 


SO 


IE90 


STA 


WOiT 


^ Sec up write cuunc 


904 5 


W) 


0E90 


LDA 


BUf'FES 




904 8 


C9 


OB 


CMP 


«on 


^ TF ilrsc byre In buffer is CR 


904* 


BO** 


tut 


5020 


^ TIFEK write out tF also 


9a«c 


EC 


ia9Ci 


INC 


WCHT 




904F 












90(F 






$020 SOS 


KRITE, WPLtsT 


; Urice oiic 1 of 2 byt ee 


9053 












91)51 


iC 


3990 


JMP 


SO 10 


; Repeat ad infinitum 


9056 












903b 
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CACE ' b SCKttlVi FILE: 







.PAIS 


























; SUBROUTIMES 














90 5 & 






















: OPEtKONS: open rhe .CONSOU: Eile for reading 












vOt6 


















9t3 


Oft 


COUST . BYT& 


Oi 


; i rEquLred p3raiii*Cflr5 for OPEN 


9 05 7 


0390 


.uoao 


CHAME 


; pachname pointer 


905 9 


00 


CktV .SYTB 


00 


; ret nun re turni.'d hf i u' 






,UORCF 


COP LI ST 


1 apt^Qn lisc paLnr^-r 


90 &C 


Oi 


.aVTE 


01 


J ItEi^rh af Dpr pa f Tia i l$r 


9050 










90 5d 




C0P[.15T .aTTE 


03 


; 0p4n for ro.idtnf; and writing 


905{^ 










90 5 £ 










90SE 








; Hsrc dldn c u&ff n [nacro. 




□ 


BRK 




p Begin SOS cfill bl<3Crl( 1 


90 5F 


C3 


.aVTE 


0C8 


; Open the console! 


9U60 




.WOBD 


COMST 


'f Pointer to pSfilmCC^r list 


906 Z 


AD 3990 


l.DA 


CHEF 


} Save Che rtiiult ref nyra 


9065' 




STA 


REF 


; For IIEA05 and W^lTEs. 


906S 


60 


RTS 






9069 
90 & 9 
90 6 9 


















90 &9 




; CETONUN; Cet cht 


device ciumtMtr of .CONSOLE 


9069 










9069 


















906 9 


02 


CDLIST .BYTE 


0! 


; 2 paramecera for CET DEV HUM 


9D6A 




.WORD 


CNAHE 


X dew n-TiBe pointer 


906C 


BO 


CONUM .BYTE 


00 


: 4ev"~nw™ goes here 


906D 










9&&D 










9060 




GETONaM 






90 6D 


00 








906b 


8t 


.BYTE 


8^ 


; Call GET DEV HUM 


90 6F 


6990 


.WOBO 


GDI. [ST 




9fl7l 


AD 6C9a 


IDA 


CDSUM 


i S«ve the result dev mm 


9074 


80 0090 


STA 


COriSNUM 


; for can^ole codtrnl 


9077 


60 


RTS 
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PACE - 7 sciteetfMa riLEi 



9078 






.!>ACE 








907fl 
9078 
















! 










90 7S 






SETCONSt set the .CONSOLE File ta suppress screen ncha 


907 S 














9a:r» 




' , . . . T X 




: :i :i I 






907S 














907 a 


03 


SETI.IST 


• SHE 


03 




3 required parmg fjjr D CO^TKO]. 


9079 


00 


CHUM 


.me 


00 




dtv nurd of .CONSOLE 


907A 


Od 




.BYTE 


OB 




tonrrnl tode = OB: screen echo 


907B 


**** 




• UORD 


CONLIET 




£ontrol~Ll5t pointer 


907 D 














9070 


00 


CONSIST 


.BYTE 


FALSE 




Disable screen et:hcN 


907E 














9076 














907 E 




srrcDNS 










907 e 


fia 0090 




LDA 


CONS HUM 




S^l. up device flumher 


90BI 


90 7990 




STA 


CNLH 




aC .CONSOLE 


90 S4 






SOS 


a CNTL, 


SET LI ST 




901)8 


60 




ETS 








9089 














9089 
90*9 
















■ 










90S9 




i 


ARMCTRLO: A™ 


tlie AcEention Event for CONTHOL-0 


90S 9 












90 8 9 
90B9 


























9089 


03 


Da 1ST 


.BYTE 


03 




3 reiiulred psns for D CBNTKOI. 


908A 


DO 




.BVTi; 


00 




dev nLsin of .CONSOLE fjces here 


90SB 


at 




,BrTE 


OB 




conTrol ctJde^ 06: 


90 8C 












AmTAttenr i'jn Evcnc 


9D6C 


iiitHk 




.WORD 


CLIST 




cailtrel list palntey 


9oaE 














908 e 




Cl.IST 








Control list 


908E 


FF 




-BYTE 


OFF 




EvBiTt priority 


908F 


02 




.BYTE 


02 




Event ID 


9090 






.UOKO 


HANDLE it 




Event handler address 


909i 


00 


BANK 


-BYTE 


DO 




Event handler faank 


9093 


11 




-BYTE 


U 




Attention char - CTRL-0 


909* 














90911 














mik 




lUWCTRLO 








9094 


AD EFFF 




LDA 


BREC 




Set up bank number 


9097 


8D 9290 




STA 


BAMX 




of event handler 


9I)9a 


AO 0090 




i.DA 






Sec up device nmober 


9090 


SO 8A90 




STA 


ONUM 




for control reqaeat 


90 AO 






SOS 


CNTL, 


OCLIST 


CONTROL call macro 


90\<i 


60 




AtS- 
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?ySGE - S SGREEtMl FILE: 



90A^ 
MAS 
90A5 
9DA5 
90A5 
90A5 
SOAi 

WAS 
90A5 

90A3 
90A5 
MAS 
MA 5 
WAS 

MAS 
90A5 



?OAS 


90A5 












SELLS 


-EOU 








; Buffer with BELg and delay: 


90AS 


07 














.BYTE 


07 






1 BEL 


90A6 


16 >(> 


16 


a 


16 


16 


Id 




.BYTE 


16, 16, 


16, 


16, 


16, 16, 16, 16, 16 ; SYNCg 


90AB 


16 16 
























TOAF 


07 














-BYTE 


07 






; BEL 


waa 


16 16 


16 




16 


16 


lb 




.BYTE 


16. 16, 


16, 


16, 


16. 15, 16, 16, 16 ; SWCs 




16 16 


























0/ 














-BYTE 


07 






; BEL 




0015 












B ELLEN 


.EOU 


♦-BELLS 






7 CdlCvlate faufffir lengcK 


MBA 


























90 eA 














HBLKl 


.BYTE 








; 4 reffulEed porameEerfi for READ 


90BB 


00 












HREFl 


.BYTE 


00 






; Tef nuto 


90 BC 
















,UORD 


HBUFl 






; data bufl4>t pointer 


9CIBE 


0100 
















0001 






; t${|uest count 


90C0 


0000 














-WORIl 


OOOO 






; tr«n5f«>r CQunt 


90C2 


























laci 


00 












HBUFl 


.BYTE 









J Buffer fer dtrentjon thacatter 


90CJ 




























03 














.BYTE 


05 






[ 3 required ^nrameters for WRITE 


90C4 


00 












H!l£F2 


.BYTE 


00 






i ref nura 


90C5 


ASM 














• WORD 


BELLE 






I darfl buffftc poincer 


9(JC7 


ISOO 
















BELLEM 






J rtyu^sc count 


90C9 




























01 












1IBLK3 


.Bm; 


01 






1 1 required parameter for CLOSE 


90CA 


00 














.BYTE 


00 






i reF nim - 0: CLOSE ail filo<: 






























00 












>IBLKf> 


.BYTE 


00 






5 requ;ireil parmo for TERMINATE 



-PAGE 



HANDUHR: Attention event hnarrdlcr subroiii^ine 

This subrfiutlrte reatis Che jctehttort cfiarncccr ^C0Nt^^OL^Q) 
frcm .console, Chen beeps chrUe, If the previous 
character va& tvSCAi'E, the pcQgratn Ceminates* 

A buffer separsce f^oia the iiLain dacs buffer is used for 
reading the atcentlon chflcaccer^ ss otheivise che 
riCEgnclan ch^jr/iccer wtjuld suiDedlmeg cLabber ch^raccer 
In the d^Cd buffi^r tii±fi:»c« iE cuuld be wrUCen* 

The bufter contLsine chcee BEL charsccer^i, sepncaced 

by a nuHber of SYNC characters* When written tn the 
console^ che5« cause a tocal delay qF about 15C n^. 
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9 SCREENUS riLE: 



SQCC 




-PACE 




90CC 




HANDLER 




90CC 


AU 0C90 


LQA 




90CF 


SD eB9S 


STA 




WD 2 


AD C490 


STA 


HREF2 


^005 








WDS 




SOS 


KI^AD HBLKi 










90D9 




SOS 


WR1T£ XBLK^ 


90DD 






9001) 


AD om 


IDA 


eUFFER 


90E0 


C9 IS 


cw 


'IB 


90E2 


DO** 




SOiO 


90E4 








90 E4 








90Ea 




SOS 




90 EC 








90 EC 


aO 94 90 


SOlO JSR 




90EF 


60 


RTS 




9()f0 








90F0 






ih * A * A * + * * ft ft A * 


90F0 








9DrO 






-Aftft A A *#**1^A Aft 


9W0 








9oro 




; E»d of 


pragraa — c* 


90FO 






90fO 
90F0 














90 FO 


tWFO 


COBEUM .EOU 


"-START 


9DIP0 




.END 





Set up Ceterence nuabcrs 
Eor console HEAD 
And rivrtiiDLe urite: 

Urue chfee to .CONSOLE 

IF l&fic Veystnike was ESCAPE 



THEN CLOSE jil flies 
and TIRHlNATE 



ELSE r«-aroi atteiicLon event 
H nd reiiunie e KeCut Ion 



A*ftj^ftft4ftAA AA 



Calculate nuDiber of bytes Ln 
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PACE - 10 SCREENSm TII&: SYHSOLTULE DUW 





LB - Uiho 






- t3 nd**F Lnpd 














B¥ - De£ 




PR 


Proc 




FC 


- Eunc 






ra - Puhltc 


PV - Private 


CS 














ARMCTRLQ 


LB 9091 


BANK 


LB 


9092 




LB 


9020 


BELLED 


AB 


00 i 5 


CUST 


L6 9CJeE 


CNAHE 


LB 


9003 


CMUM 


Lfi 


9079 


CODELEN 




QOprt 


COP LIST 


LB 905D 


CREK 


LB 


9039 


DCLIST 


LB 


9039 




AB 


UOBJ 


CDLtST 


LB 90M 


CaWH 


LB 


906C 


UETQNUM 


LB 


906D 


HAMDUR 


LB 


90CC 


HflU4 


L8 90eB 


HB UFI 


LB 


MC2 


HREFl 


LB 


90 BB 


HRKF2 


LB 


900 4 


tlEAO 


AC OOCA 


REF 


LB 


KUQ 


RBEF 


LB 


SOJl 


SCREENHn 


PR 




STAM 


AB ?000 


TR'JE 


AB 


0080 


UCNT 


LB 


90IE 


«PLI5T 


LB 


901 A 


SELLS 


l,« 90^5 


BKEC 


AB 


FPEF 


BUFFER 


LB 


iOOE 








COLlSt 


L» WS6 


C0KL15T 


LB 


90 TD 




:.s 


9000 








DNUM 


LB 90 3A 


FALSE 


AB 


0000 


FEKI.IST 


LB 


9010 








KBLKI 


LB 


HBLK2 


LIS 


9oei 


Hill .HI 


LB 


90C9 








OPEKCONS 


LB 505 E 


RCLIST 


LS 


9012 


RCNT 


LB 


40IS 










LB 907E 


SETLIST 


LB 


9079 


SOS 


MC 










UREF 


LB 90 IB 


URJTF. 


AB 


O0C8 
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PACE - H SCREENWR FILE: 

Current mlnLinuEn space Is 156^7 words. 

Assembly cornplecg: 194 lines 

frtors f L^i/lK'^d on this Aftsouibly 



tnterpreters and Modules ii3 



7.3 Creating Interpreter Files 



The Apple It! Pascal Assembler reads a source text file of assembly- 
language statements and creates a code file consisting of a header block, 
a code section, and a relocation section, if the code file is relocatable. A 
SOS interpreter file must be in a format different from the standard code 
file format that is used for a module: 

• It must be in absolute format, beginning at the proper memory location. 

• It must have a special header that identifies the file as an interpreter, 
and the standard header and trailer must be removed. 

• It must be named SOS.INTERP before it can be booted. 

A utility program, lyiakelnterp, transforms code files into 
interpreter files. Its use is described in Appendix C. 

7.4 Assembly-Language Modules 



An interpreter that is too large to fit into the the memory space allocated 
for it can be split up into a main interpreter and one or more assembly- 
language modules. An interpreter can also use modules if it is made to be 
extensible, or if it wishes to swap sections of machine code in and out of 
memory. A language interpreter may use modules to allow the user 
programs it interprets to call assembly-language subroutines. 

SOS does not directly support creating, loading, or maintaining modules; 
modules are defined, loaded, and called by the interpreter only. 

Whereas an interpreter must be written and assembled tn absolute code, 
a module can be in either absolute or relocatable format. A stand-alone 
interpreter performing an application will probably only have to support 
absolute modules, if any, A language interpreter, however, may support 
relocatable modules, as do the BASIC and Pascal interpreters. 
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7.4. 1 Using Your Own Modules 



An interpreter can use the REQUEST SEG call to request a fixed memory 

segment in tree memory, then foad a 6502 code file into this space and 
execute its code. An interpreter can execute modules located in bank- 
switched memory by using the technique described in section 2.4.1, 

In this way, an interpreter can have several sections of overlay code^ 
subroutines that are swapped into a certain memory space only when 
they are needed, and are replaced by ottier code when their usefulness is 
expended. This is illustrated in Figure 7-2. 



module 



module 



free memory 



free memory 



driver 



driver 



SOS kernel 



driver 



\$2000 



interprsler 



SOS kernel 



\ last 
( bank 



SA000 



$FFFF 



Figure 7-2. Interpreter and I^odules 



Rather than allocating free memory, an interpreter can also overlay code 
into itself and execute it without ban i< -switching. This technique is 
dangerous unless you carefully control which parts of the interpreter are 
being overwritten. 
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7A. 2 BASIC and Pascal Modules 

The Apple Pascal and Business BASIC languages both have facilities for 
loading assembly-language modules or linking them with a Pascal or 
BASIC program. The modules are in the relocatable format produced by 
the Apple Pascal Assembler; the Pascal and BASIC interpreters are both 
designed to load, relocate, and execute files In this format. 

The BASIC and Pascal interpreters each place a module in a convenient 
place In memory, then use the relocation information in the code file to 
alter the program code to run in its new location. A BASIC program 
communicates with modules via PERFORM and EXFN statements; a 
Pascal program uses EXTERNAL PROCEDURE and FUNCTION calls. 
Whereas invokable modules used by BASIC are loaded dynamically at run 
time, modules used by Pascal are linked in with the Pascal host program 
during a post-compilation linking phase, and are stored as part of the final 
code file. 

Both the BASIC and Pascal interpreters pass parameters to their modules 
via the interpreter's stack. The modules remove and store the return 
information, then pull the parameter bytes off the stack and process them 
When they are finished, they push the return information back on the 
stack and perform an RTS. 

A module used by the BASIC or Pascal interpreter does not need 
y to know any entry points in the interpreter 

A module can access your programs or data by means of pointer 
parameters. The interpreter passes the two bytes of the pointer on the 
stack, and sets up the X-bytes of the pointer in a fixed location in the 
interpreter's X-page. The module pulls the pointer off the stack and stores 
its pointers in the proper places in the zero page; it can then use extended 
addressing to access the host program's data structures. 

You can find more information on the use of assembly-language modules 
with Pascal in the Apple III Pascal Program Preparation Tools manual, in 
the chapter The Assembler 
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7.4.3 Creating Modules 

Modules can be in either of two formats: absolute and relocatable. The 
absolute form is easier to load, but less versatile. If you can be sure a 
particular region of memory will be available for a module, you can 
assemble that module to fit into that region, and write a routine into your 
interpreter to load that module into that region. In doing so, you must take 
into consideration whether assembling a module to run in a particular 
region will affect the interpreter's memory requirements. You can also do 
this with a number of modules: you can even assemble several modules 
for the same region, if they are to be used one at a time and swapped in 
as needed. 

Relocatable modules can go anywhere in free memory, so they can more 
easily be used by machines of different memory sizes, driver sets, and so 
forth. A language interpreter that supports modules will probably support 
relocatable modules. However, such an interpreter must take care of the 
relocation itself. This task goes beyond thescope of this manual. The data 
formats of relocatable assembly-language code files are described in 
Appendix E; more detail is in the Apple III Pascal Technical Reference 
Manual. If you are designing an interpreter that supports relocatable 
modules and need further assistance, contact the Apple PCS Division 
Technical Support Department. 
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a. 1 Types of SOS Calls 



An interpreter communicates with SOS primarily through SOS calls. 
A SOS call is a request that SOS perform an action or return some 
information about a file, device, or memory segment. 

SOS calls fall into four categories: 

• File calls, which manipulate files according to the file model 
presented in Chapter 4; 

• Device calls, which manipulate devices according to the device 
model presented in Chapter 3; 

• Memory calls, which allocate and release memory for 
interpreters and keep track of areas of free memory; and 

• Utility calls, which access the system clock, the event fence, 
and other resources. 

The individual SOS calls are presented in Volume 2. The way a SOS call 
is made, however, is the same regardless of the function of the particular 
call; the remainder of this section discusses how an interpreter makes 
SOS calls. 

8.2 Form of a SOS Call 



A SOS call has three parts: the call block, the required parameter list, and 
the optional parameter list. Not every call has every part. The parts need 
not be in any particular order, and need not be contiguous, as they are 
linked by pointers. 

8.2.1 The Call Block 

A SOS call begins with the call block, a four- byte sequence executed as 
part of an interpreter's code. Figure 8-1 is a diagram of a call block, along 
with the code implementing it: 
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54F9ig0 CAL8LK BRK 

&1FAIC9 ,BVTE0C8;OPEN 

54FB 13052 .WORD PL 1ST , PTR 

$54FA 
$54FB 
$54FC 



$00 


BRK 


$C8 


calt_num 




value 


$20 


parm_list 


$52 


pointer 



Figure 8-1. SOS Call Block 
The SOS call block has three fields: 
BRK (1 byte): 

This field always contains the BRK opcode, $00; 



call num {1 byte): 

This field contains the SOS call number, which must correspond to a valid 
SOS call. 



parm^list (2 bytes) : 

This field contains a pointer to the required parameter list for this SOS 
call. The parm_list is an address in S-bank notation, $nnnn. which specifies 
a location in the current bank or in the S-bank, never in the zero page, The 
location specified contains the first byte of the required parameter list for 
the call being nnade: the required parameter list is described below. 

If the call_num or the parmjist is invalid, SOS returns an error code to 
the caller. 



If the format of the SOS call is correct, SOS performs the requested 
action. After the call is completed, SOS restores the state of the machine 
(the values in the X- and Y-registers and all status flags except Z and N) 
and returns control to the caller. If an error was encountered, the error 
code is returned in the accumulator. If the call was error-free, the 
accumulator returns $00. You can think of a SOS call as a 4-byte LDA 
#ERRORCODE instruction; you can check for the presence of an error 
code with the BEQ and BNE instructions. 
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8.2.2 The Required Parameter L ist 

The required parameter list is a table in memory that ttie interpreter uses 
to communicate with SOS. It is Irom here that a SOS call gets the 
information it needs, and it is also here that the call returns information 
to the caller. 

Each SOS call expects a certain number of parameters: the number and 
type of parameters is different for each call. But the first byte of the 
required parameter list for any SOS call always contains the number of 
parameters for the call (not the number of bytes in the list). SOS checks 
this number against the number of parameters the call is expecting, to 
verify that you've supplied thecorrect list for that call. If the numbers don't 
match, SOS returns an error message. 

Figure 8-2 is a required parameter list: 
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54F9|0fl CALBLK 
54FA|C8 


BRK 
,BYTE 


0CS : OPEN 


$54F9 


$00 


BRK 


54FB 12052 


.WORD 


PLIST : PTR 


$54FA 


$C8 


call niim 

value 








$54FB 


$20 


parmlist 








$5^FG 


$52 


pointer 



5220104 PLIST BYTE 

5221 10652 PATHN WORD 

5223100 REFNUM BYTE 

5224 10052 OPLIST WORD 

5226 104 OPLEN .BYTE 



04 

FILE1;PTR $5220 
00 : VALUE 
REQACC;PTR $5221 
04 ; VALUE 

$5222 
$5223 
$5224 
S5225 
$5226 



$04 


pa rm count 

value 


$06 


pathname 


$052 


pointer 


$00 


ref num 

resuU 


$00 


optlDn_lrst 


$52 


pointer 


$04 


length 

value 



Figure 8-2. The Required Parameter List 

This list contains all the required parameters for the call. A value must be 
supplied for each parameter: no default values are assumed, The number 
of parameters and the length of the required parameter list are constant 
for any one SOS call, and usualiy different for every call. 

Parameters are of the four types listed below. 

• A value parameter is 1 , 2, or 4 data bytes passed from the caller to 
SOS. The caller places a value in the proper field of the parameter 
list, destroying its previous contents; SOS reads it without 
changing it, 

• A result parameter is 1 , 2, or 4 data bytes returned by SOS to the 
caller. SOS places a result in the proper field of the parameter list, 
destroying its previous contents; the caller reads the result 
without changing it. 
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• A value/result parameter is 1 , 2, or 4 data bytes that are read and 
modified by SOS: the value and the result share the same space. 
The caller places a value in the proper field of the parameter list, 
destroying its previous contents; SOS reads the value and 
replaces it with a result, destroying the value. Few parameters 
are of this type. 

• A pointer parameter is a 2-byte address (in any format — see 
section 8.3.1 below) that specifies the beginning of a buffer 
established by the caller, SOS uses the pointer to read information 
from the buffer or to return data to the same buffer. Pointers allow 
you to exchange variable-length data with SOS. Pointers are 
discussed in more detail in section 8.3. 

The calling program supplies a pointer to SOS: SOS never returns or 
alters a pointer. It either reads from or writes to the buffer the pointer 
points to. 

Some required parameter lists can be used for more than one call, usually 
(for a pair of complementary calls. In the case of GET_FILE_INFO and 
SET_FILE_INFO (which read and change miscellaneous information 
about a file), you can call the former, examine its results in the required 
parameter list, perhaps change them, and call the fatter with the same 
required parameter list to make your changes take effect. 

8.2.3 The Optional Parameter List 

Some SOS calls have parameters that need not be supplied for their 
simplest operation These parameters are stored in an optional parameter 
list. A pointer (option list) in the required parameter list specifies the first 
byte in the optional parameter list, and a length parameter in the required 
parameter list indicates how many bytes of optional parameters are 
supplied. Figure 8-3 is an optional parameter list: 
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54F9I00 

S4FAIC8 

54FBI2052 



CALBLK 



BRK 

.BYTE 
WORD 



see. OPEN 
PL 1ST ; PTR 



$54F9 
$54FA 



$54FB 



$54FC 



5220104 
5221 10652 
5223 00 
522410052 
5226104 



PLIST 

PATHN 

REFNUM 

OPLIST 
OPLEN 



.BYTE 

WORD 

BYTE 

WORD 

.BYTE 



04 

FILE1 ;PTR 
00; VALUE 
REOACC ; PTR 
04 ; VALUE 



$5220 



$5221 



$5222 



$5223 



$5224 



$5225 
$5226 

5200103 REQACC BYTE 03; VALUE 
5201 |04 PAGES WORD 04; VALUE 
520210055 lOBUF .WORD 00; PTR 

$5201 



$5202 
$5203 



m 


BRK 


$cs 


callnum 

value 


$20 


parm_llst 


$52 


pointer 




$04 


pa rm count 

value 


$06 


pathname 


$52 


pointer 


$00 


ret_mini 

result 


$00 


option_|[5t 


$52 


pointer 


$04 


length 

value 




$03 


req access 

value 


$04 


pages 

value 


$00 


io_ buffer 


$55 


pointer 



Figure 8-3, Optional Parameter List 
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You can supply any number of optional parameters, depending upon 
what you want the call to do. If the length of the optional parameter list 
is $00, the call will expect no optional parameters. If the length is non- 
zero, the call will expect as many optional parameters as can fit In that 
number of bytes. 

Some calls supply default values for optional parameters that are not 
supplied; seethe individual call description. 

8.3 Pointer Address Extension 



Some parameters in the parameter lists are pointers, which are simply 
addresses of other data structures (usually buffers) in memory. You can 
supply these addresses in S-bank. current-bank, indirect, or extended 
format, all of which are described in section 2.1. 

When you make a SOS call involving a buffer, you must give a pointer 
to the buffer, and the number of bytes to be acted on. For example, the 
READ call requires a data_buffer pointer and a request_counl parameter 
specifying how many bytes are to be read, SOS takes care of incrementing 
the pointer to read successive bytes: you need only tell it how to find the 
first byte. 

There are two kinds of pointers: 

• A direct pointer is a two-byte address in current-bank or S-bank 
format. This address is that of the beginning of the buffer in the 
current or S-bank. 

• A indirect pointer is a two-byte address whose high byte is $00, 
This address specifies a zero-page location: the location contains 
the indirect or extended address of the beginning of the buffer 

in memory. 

SOS converts both kinds of pointers into extended addresses. It does not 
change the pointers in your parameter list: instead it moves them to its 
own zero page so it can use them as extended addresses. The following 
paragraphs describe how SOS handles different kinds of pointers. 
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For all pointer conversions, SOS checl<s only that the pointer 
indicates a valid location: it does not ensure that the structure 
pointed to is in a valid place. It does not verify that the location 
pointed to actually exists in system RAM. There are limits on how 
big and where the buffer can be: such restrictions are discussed 
with each conversion. 



8.3.1 Direct Pointers 

A direct pointer can specify a location in either the S-bank or the current 
bank. If the tatter, the current bank can be either bank or some other 
bank. These cases are considered here. 

Figure 8-4 shows a direct pointer: 



$52A4 
$62A5 



$41 pointer 
low byte 



$71 pointer 
high byte 







data 


$7141 
$7142 















Figure 8-4. A Direct Pointer 



8.3.1.1 Direct Pointers to S-Bank Loca Hons 

SOS moves the pointer directly to its zero page v/ithout conversion, and 
sets the X-byte of the pointer to $00 to form a normal indirect address. 

Original Pointer Extended Form 



$nnnn $A000 to $B7FF 



$00:nnnn $00:A000 to $00:B7FF 
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A buffer that begins in tfie S-bank must reside in a contiguous 
region of S-bank memory. For example, if you start reading from 
a buffer beginning at location $A000and read $200 bytes, you will 
cover the address range $A000 to $A1 FF. If you read beyond 
$B7FF, you will run into SOS's region. 

8.3.1.2 Direct Pointers to Current BankL oca tions 

SOS converts such pointers to extended form. If the current bank is not 
bank 0, SOS creates an X-byte based on the caller's current bank number, b. 
The result isconverled to ensure that the resulting pointer specif ies 
neither the zero page nor the last page of a bank pair. 

Original Pointer (bank <> 0] Extended Form 



$nnnn $2000 to $21 FF $xx:nnnn $8b-1;8000 to $8b-1:81FF 

$nnnn $2200 to $9FFF $xx:nnnn $8b:0200 to $8b:7FFF 

If the current bank is bank 0, then the address is converted to an 
extended address whose X-byte is $8F. 

Original Pointer (bank = 0) Extended Form 



mnnnn $0:2000 to $0:9FFF $aF:nnnn $8F:2000 to $8F:9FFF 

A buffer that begins in switched memory must lie entirely within 
switched memory. If a butter begins between $b:20M and 
$b;9FFF. it can extend up to 64K bytes, and can wrap across 
bank boundaries, if b is not zero. For exampte, if you start reading 
from a butter at $b:9F00 and read $200 bytes, you will cover the 
ranges $b;9F00 to $b:9FFF and $b+ 1:2000 to $b+1 :20FF However 
the buffer may not go Into the address range $A000 to $FFFF 



Indirect Pointers 

Indirect pointers are always stored on the caller's zero page. The two-byte 
value in the parameter list is the address of the pointer on zero page. 
When SOS processes an indirect pointer, it moves the two bytes of the 
pointer from the caller's zero page to its own zero page, and also moves 
the X-byte of that pointer to its own X-page. 
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An indirect pointer can have an X-byte equal or unequal to zero: if it is 
equal to zero, the bank number can likewise be equal or unequal to zero. 
These cases are considered here. 

Figure 8-5 shows an indirect pointer: 



$62A4 



$20 pointer 
low byte 



$00 pointer 
high byte 







$0020 




$0021 


$41 pointer 
low byte 

$71 pointer 
high byte 










$1620 




$1621 


$81 pointer 
X-byle 







$ai-.7i4i 

$81:7142 



data 



Figure 8-5. An Indirect Pointer 



8.3.2. 1 Indirect Pointers with an X-Byte of $00 

These pointers are converted by SOS to full extended addresses, as in 
the direct-pointer examples above. An indirect pointer with an X-byte of 
013 is identical to a direct pointer and follows the cases shown above. 
SOS creates an X-byte based on the caller's current bank number, b. 
The address may be converted to prevent it from pointing to the zero 
page, as shown in the first line below. 

Original Pointer Extended Form 



$00:nnnn $00:$2000 to $00:$21 FF $xx:nnnn $8b-1 :8000 to $8b-1 :81 FF 
$m:nnnn $00;$2200 to $0t);$9FFF $xx:nnnn 8b:0200 to $8b:7FFF 

If the current bank is bank 0, tfie address is converted to an extended 
address whose X-byte is $8F. 
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Original Pointer (bank - 0) 



Extended Form 



$00:nnnn $00:2000 to $00:9FFF $8F:nnnn $8F:2000 to $8F:9FFF 



A butter that begins in switched iTiemo[7 must lie entirely witiiin 

y switched memory. If a buffer begins between $b:2000 and 

$b:9FFF, it can extend up to 64K bytes, and can wrap across 
bank boundaries, if b is not zero. For example, if you start reading 
from a buffer at $b:9F00 and read $200 bytes, you will cover tfie 
ranges $b:9F00 to $b:9FFF and $b+1:a000 to $b*1 :20FF, However, 
ttie buffer may not go into tne address range $A000 to $FFFF. 



8.3.2. 2 Indirect Pointers with an X-Byte Between $80 and $8F 
Ttiese pointers are invalid if they point to the zero page or stack: 
Original Pointer Extended Form 



$80:nnnn $80:0000 to $80:01 FF Invalid 
$8x:nnnn $8b:0000 to $8b:00FF Invalid 

The range of addresses in the second line could be replaced by alternate 
form, $8b-1:8000 to $8b-1:80FF. This trick doesn't work in the first case, 
as bank is the lowest bank. 

Indirect pointers that have an X-byte between $80 and $8E are converted 
only to ensure that addresses produced by indexing on them do not point 
to the zero page. The pointers below are converted: 

Original Pointer Extended Form 



$8x:nnnn $8b:0100 to $80:01 FF $8x:nnnn $8b-1 :8100 to $8b- 1 :81 FF 

$8x:nnnn $8b:FF00 to $80:FFFF $8x:nnnn $8b+1 :7F00 to $8b+1 :7FFF 

The pointers below are unchanged: 

Original Pointer Extended Form 




$8x:nnnn $8b:0200 to $8b:FEFF %8x:nnnn $8b:0200 to $8b:FEFF 
$8F:nnnn $8F:2000 to $8F: B7FF $dF:nnnn $8b:2000 to $8b:B7FF 
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The X-byte $8F is a special case that looks like a direct pointer if b is zero. 

I^^^J The buffer that the above address points to can contain up to$FFFF 

bytes, and can wrap from one switched bank to another. SOS will handle 
all the pointer manipulations automatically. A buffer cannot, however, 
cross over into S-bank space; and it must reside in no more than three 
adjacent banks. 



8.4 Name Parameters 



Many SOS calls use device names, volume names, or pathnames as 
parameters. Since a name is a variable-length siring of characters, it 
cannot be included in a parameter list: you must supply a pointer to a 
name. The pointer can be specified in any of the formats described above. 
Figure 8-6 illustrates the format of a name parameter. 



$32A0 


$02 




$32A1 


$83 


dev_rame 




S32A2 


$5A 


pointer 




S32A3 


$W 


de(»_mjm 

result 












S5AB3 


$03 


length 

value ' 






$5AB4 


$2E 




$5AB5 


S44 


■D' 




$5AB6 


$31 


•r 





Figure 8-6. Format of a Name Parameter 
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The first byte pointed to by the parameter contains the number of 
characters in the rest of the name; the bytes immediately following 
contain the individual characters in sequence. 

Device and volume names can contain up to 15 characters: such names 
use 2 to 16 bytes of storage. Pathnames can be up to 255 characters in 
length: such names require 2 to 256 bytes of storage. 

8.5 SOS Can Error Reporting 



After execution of a SOS call, the accumulator contains the error code 
reported by the call, and the N and Z status flags are updated accordingly. 
All other registers are returned to their state before the call. If the call was 
completed successfully, the accumulator contains $00; a BEQ instruction 
can detect a successful SOS call. 

Error numbers range from $01 to $FF. Errors can be classified into groups 
by their error numbers; 

• Error codes $01 through $05 indicate a problem with the form of 
the SOS call, or its parameters or pointers. 

• Error codes $10 through $2F indicate device call errors Either a 
requested operation is not supported by SOS, or the operation 
cannot be performed due to interface problems with a device. 
Some of these errors can also be produced by file calls. 

• Error codes $30 through $3F are generated by individual device 
drivers, and they indicate a problem in a particular device, 

• Error codes $40 through $5A indicate file call errors. 

• Error codes $70 through $7F indicate utility call errors. 

• Error codes $E0 through SEF indicate memory call errors. 

These errors can be generated by SOS for any SOS call: 
$01: Invalid SOS call number (BADSCNUM) 

The byte immediately follow/ing the BRK instruction ($00) in the SOS call 
block is not the number of a currently defined SOS call. 
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$02: Invalid caller zero page (BAOCZPAGE) 

SOS requires that the interpreter use page $1 A as its zero page when 
calling SOS. 

$03: Invalid indirect pointer X-byte (BADXBYTE) 

The extension (X-) byte of an indirect pointer is invalid. Legal values for 
this byte are 

$00 Indirect, current bank 

$80 througfi $8E indirect, extend bank 
$8F Indirect, S/0 bank 

$04: Invalid SOS call parameter couni (BADSCPCNT) 

The f irst byte of the required parameter list contains a parameter count 
not expected by the specified SOS call. Either the call number is incorrect 
or the call is using the wrong required parameter list. 

$B5: SOS call pointer out ol bounds (BADSCBNDS) 

A SOS call pointer parameter is within a proscribed range of memory. 
Either the required parameter list resides on zero page or a pointer is 
attempting to point into SOS. The proscribed memory ranges are: 

$0100through $01FF Restricted for SOS 
$B800 through $FFFF Restricted for SOS 

$xx:0000 through $xx:00FF Zero Page 



$8F:0100 through $8F:01FF Restricted for SOS 
$8F:B800 through S8F:FFFF Restricted for SOS 



162 SOS Reference Manual \ 



Index 193 { 

































- 

























1 — 1 


1 — 




- . 






H 




























ndex 































Page references in Volume 2 are shown in square brackets [ ^ 



A 

absolute 

code 120 

mode 29 

modules 143 

or relocatable format 143 
access 63, 68,81,84,88, 90, [11], 
[18] 

data 10,27,29-32 
patfi{s) 52 

information 64-66 

maximum number of 53 

multiple 52 
techniques 27-38 
accessing 

a logical device 41 

zero page and stack, warning 

17 

ACCSERR [55] 
accumulator 110 
ADC 31 
address (es) 15 

bank-switched 10, 12, 30,32 

bus 10 

conversion 25, 32-35 
example 1 22 



current-bank 12.38 
extended 13,38 

notation 15 
extension, pointer 154-159 
invalid 13 
limit 122 
notation 

bank-swttched 15 

extended 15 

segment 23-27 
of blocks 96, 97 
of event handler 108 
relocatable [138] 
risky 15 
risky regions 32 
S-bank 12,38 
segment 24, 38 

notation, S-bank 25 
three-byte 13 
two- byte 12 
addressing 

bank-switched memory 10-13, 

30- 31 

enhanced indirect 10, 13-16, 

31- 32 
indirect-X 13 
indirect-Y 13 
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modes 10-16 
enhanced 8 

module 27-29 

normal indirect 14 

restrictions 15 

subroutine 27-29 
ALCERR [128] 
algorithms 32 

reading a directory file 91-92 

incrementing a pointer 36-37 

sample 27 
allocate memory 25 
allocation 7, 23 

of a segment of memory 121 

scheme, block 95 
analog inputs 113 
AND 31 

Apple III, overview of 3-8 
Apple 1 1 1 Pascal Assembler 145, 

[132], [134] 
Apple III Processor xvii 
arming events 108,125 
.ASCII [139] 
ASCII equivalents [117] 
Assembler, Apple Pascal 1 45, 

[132], [134] 
assembly language 5 

codefile(s) [131-139] 
data formats for relocatable 
146 

module 19,118,143-146 

linking 145 

loading 145 
procedure [136] 

attribute tables [136], [137] 
programming xvii 
asynchronous operations 5 

of device drivers 104 
attribute table [136], [138] 
assembly-language procedure 

[136] 
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procedure [136] 
.AUDIO [111] 
audio [111] 

auxjype 64. 88, [5], [14], [19] 
B 

B field 14 

backup bit 90, [12], [18] 
Backup III 90, [13] 
BADBKPG [88] 
BADBRK [127] 
BADBUFNUM [128] 
BADBUFSIZ [128] 
BADCHGMODE [88] 
BADCTL [71 ] 
BADCTLPARM [71] 
BADCZPAGE 161 
BADDNUM [71] 
BADINT [127] 
BADJIVIODE [104] 
BADLSTCNT [56] 
BADOP [72] 
BADPATH [53] 
BADPGCNT [88] 
BADREFNUM [54] 
BADREQCODE [71] 
BADSCBNDS 161 
BADSCNUM 160 
BADSCPCNT 161 
BADSEGNUM [88] 
BADSRCHMODE [88] 
BADSYSBUF [56] 
BADSYSCALL [127) 
BADXBYTE 161 
BCBERR [128] 
bank 

S0 16 

current 12 

highest 1 1 
swfitchable 15 
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number 15 

pair 13,14 
highest 15 

part of segment address 25 

register 11,19,28 
restoring contents of 31 

switchable 1 1 
bank-pair field 14 
Isank-switched address 10, 12, 

30. 32 

as intermediate form 32 

notation 1 5 
bank-switcfied memory 

addressing 10-13,30-31 
bank-switclned notation 23 
bank-switclning 27,28.30 

for data access 30 

for module execution 30 

restrictions 28 
base 23, 122, [43], [481, [75], [78], 

[83] 
BASE 122 

base-relative relocation table 

[138] 
BASIC 118,143 

and Pascal modules 145 

interpreter 1 45 

program 145 
BCS [139] 
bibliography [141] 
bit 

backup 90, [12], [18] 
destroy-enable [12]. [18] 
enhanced-addressing 14 
map 54 

read-enabte [12]. [18] 
rename-enable [12], [18] 
write-enable [12], [181 

bitmappointer 82 

BITMAPADR [56] 

.BLOCK [139] 



block(s) 77 

addresses of 96,97 
allocation 

for sparse files 98 

scheme 95 
altering configuration 46 
can 148-149, [x] 
configuration 43 

altering 46 
data 93, 96 
device 8, 40, 76 

logical 63 

status request $00 [60] 
device information (DIB) 43 
DIB configuration 43 
file 50-56.62 
control 64 
structure of 50-51 
index 93, 94 
key 77,82.93,97 
logical 77 

master index 94. 96, 97 

maximum index 94 

on a volume 77 

SOS call [103] 

subindex 94.96 

total 45. 82 
blocks used 63,87, [19] 
BNE |l39] 
bootstrap 

errors [128] 

loader 77, 93 
BRK 149 

instruction 8 
BTSERR [55] 
buffer 

data 50. [117] 
editing [117] 

I/O 50 

space, for drivers 21 
string [117], [118] 
BUFTBLFULL [56] 
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.BYTE [139] 
byte 99, [133] 

extension 14, 31 (See also 

X-byte) 
locating in a standard 

file 98-99 
numbering 51 
order of pointers 79 
position, logical 98 

o 

call(s) 

block 148-149, [x] 

SOS [103] 
choosing [114] 
coding TERMINATE 131 
D_CONTROL 128 
device 46-47, [58-71] 

errors [71-72] 

management 5 
errors 

device 160, [71-72], [125] 

file 160. [53-56], [125-126] 

memor/ 160, [88] 

utility 160, [104], [126] 
file 69-73, [2-53] 

errors [53-56] 

management 5 
FIND_SEG 30 
form of the SOS 160 
memory 25-27, [74-87] 
errors 188] 
management 5 
OPEN 128 
REQUEST_SEG 30 
SOS 8 

error reporting 160 

form of a 148-154 

types of 148 
utility [90-103] 

errors [104] 

management 5 



call_num 149, [xi] 
capacity of a file, maximum 94 
carr/ 15 
CFCBFULL [53] 
changing device 
name 46 
subtype 46 
type 46 
changing slot number 46 
changemode [81 ) 
CHANGE_SEG 26, [81-82] 
character 
device 8, 40 
control code $01 [64] 
control code $02 [64] 
status request $01 [60] 
status request $02 [61] 
f[le(s) 50-56, 57 

structure of 50-51 
line-termination 67 
newline 67 
null (ASCII $00) 97 
streams 40 
termination 67 
circumvention of programming 

restnctions 3 
clock 112-113. [95], [97], [98] 
rate 1 9 
system 1 1 2 
CLOSE 66,68,72.90, [39-40] 
closed files 52-53 
closing files before TERMINATE 

[103] 
CMP 31 
code 

file(s) 145 
data formats of relocatable 
assembly-language 146 
organization [132] 
assembly-language [131-139] 
code part of [135] 
fragments, examples xiv 
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interpreter, executing 10 

part of a code file 119,121. 
[132], [135] 

segments, executing 27 

sharing 44 

procedure [136] 
code length 120 
CODEADDR [134] 
CODELENG [134] 
colon 15 

connmand interpreter [103] 
comnnDn code 44 
common file structure 3 
common foundation for 

software 3 

defined 2 « 
communicating witfi ttie 

device 42 
comparing two pointers 37-3S 
compatibility with future 

versions 18 
conditions for enhanced indirect 

addressing 31 
configuration block 43 

alter 46 

DIB 43 
conflicts 

between interrupts 104 

with zero page 16 
.CONSOLE 66,105,108,125, 

[109] 
console 40 

constant, relocation [138] 
control 

block, file 64 

flow of 27 

transfer 28 
CONTROL-C [117] 
CONTROL-RESET [117] 
controf_code [63] 

$0 1 , character device [64] 

$02, character device [64] 
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copy-protection [103] 
copying sparse files 98 
CPTERR [55] 
CPU 104 

CREATE 68, 69, 90, 98, [3-6] 
creating interpreter files 143 
creation date and time 64, 81 , 84, 

88, 89-90 

field 89-90 
current 

bank 12 

direct pointers to 156 

directory 62 

position marker 51 
current-bank 

address 12,38 

form 13 
cylinders 77 

D 

-Dl [109] 
.D2 [109] 
,D3 [109] 
.D4 [109] 

D_CONTROL 45, 47, 108, 125, 

128, [63-64], [118] 
D_INFO 43, 45, 47, [67-71 ] 
D_STATUS 45, 46, [59-61], [118] 
data 

access 10,27 29-32 
bank-switching for 30 

and buffer storage 19 

block 93, 95, 96 

buffer 50, [117] 
editing [117] 

formats of relocatable 
assembly-language code 
files 146 

in free memory 30 
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data block 99 

data buffer [35], [37] 

date and time 

creation 64, 81 , 84, 88, 89-90 

format 90 

last mod 64 , 88, 89-90. [14], 
[19] 

decimal numbers xix 
decimal point xix 
DESTROY 68, 69, [7-8] 
destroy-enabie bit [12], [18] 
detecting an event 105 
dev_nanie 43, 60. [23], [65], [67] 
dev_num 43 , [59 ] , {63] . [ 65] , [67 ] 
dev_type 44, 45, [68] 
device(s) 8, 40-42 

adding a 46 

block 8, 40 

call<s) 46-47 
errors 160, [125] 

changing name of 46 

character 8, 40 

communicating with the 42 

control information 45 

correspondence 
logical/physical 54 
special cases of 54 

defined as iogical device 54 

driver (s) 5,41,77 104,107, 
108, 125 

asynchronous operation of 
104 

environment 20-21 
errors, individual 160 
graphics 16 
standard [109-111] 
memory placement 21 

independence 7,67 

information 43-44 
block (DIB) 43 

input 40 



logical 40 

block 53 
management calls 5 
multiple logical 54 
name(s) 41 -42, 44, 50, 55. 60 

illegal 42 

legal 42 

syntax 42 
number 44 
operations on 45-46 
output 40 
peripheral 8, 104 
physical 40 
random -access 7 
removing a 46 
requests 50 
sequential-access 7 
status information 45 
subtype 44 

changing 46 
type 44 

changing 46 
device-independent I/O 67 
DIB 

configuration block 43 

header 43 
dictionary 8 

current 62 

entry 62 
procedure [135], [136] 

error (DIRERR) [55] 

file 57-58 

formates) 78-92 

header 78 
storage formats 76 

segment [132], [134] 

volume 54, 57 78 
digit(s) 42,56 

hexadecimal 12 
direct pointer 154,155 

to S-bank locations 1 55 
directory file, reading a 91 -92 
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DIRERR [551 
DtRFULL [55] 
disarming events 108 
Disk III driver 41 
disk drives 40 
disk, flexible 42,77,93 
DISKSW [72] 
dispatching routine 28 
displacement [43], [48] 
Display/Edit function [117] 
DNFERR [71] 
dollar signs xviii, xix 
driver 

device See device driver 
module 41 

placement of 44 
DRIVER FILE NOT FOUND [129] 
DRIVER FILE TOO LARGE [129] 
DUPERR [54] 
DUPVOL [56] 

B 

E-bit 14 

editing data buffer [117] 
EMPTY DRIVER FILE [129] 
empty file 65 

end=of-file marker See EOF 
enhanced 

addressing bit 14 

addressing modes 8 

indirect addressing 10, 13-16, 
27,30,31-32 
conditions for 31 
ENTERIC [138j 
entries_per_ block 82, 85, 92 
entry (entries) 86 

active 86 

directory 62 

FOB 53, 62 

format compatibility 91 

inactive 86 
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storage formats of 76 
enlryjength 81.84,92 
environment 

attributes 19 

execution 16-22 

interpreter 18-19 

SOS device driver 20-21 

SOS Kernel 19-20 

summary 22 
EOF 5 1 , 53 , 63, 64-65 , 68 , 87, 89 , 

94,95,96, 97, 98, [5], [19], [49] 

limit 94 

movement of 
automatic 65 
manual 65-66 

updating 65 
EOFEBR [55] 
EOR 31 
error(s} [124] 

bootstrap [128] 

device call [125] 

file call (125] 

messages [123-130] 

numbers range 160 

reporting, SOS call 160 

SOS 
fatal [124], [126] 
general [124] 
non-fatal [124] 

utility call [126] 
event(s) 5, 104-115 

any-key 105 

arming, example 129 

arming and response 105,108, 
125 

attention 105 
detecting an 105 
disarming 108 
existing 108 
fence 106,109-110 
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handter(s) 5,107,110-111,125 

address of 108 

examples 129 
handling 106, 107 

system status during 1 1 1 
identifier <ID) 108 
mechanism, sample 126,129. 

139 

priority 105, 108 

processing 106 

queue 106, 108-109 
order 109 
overflow [127] 

summary of 112 
EVQOVFL [127] 
examples 

code fragments xvili 

sample programs xviii 
executing 

code segments 27 

interpreter code 10 
execution 

environment 16-22 

speed 19 
ExerSOS (113-119) 
EXFN 145 

extended to bank-switched 
address conversion 34-35 
extension byte 14,31 {See also 
X-byte) 

extension, pointer address 154 
EXTERNAL PROCEDURE 145 
eye symbol xv 

F 

FCB 52 

entry 53,62 
FCBERR [128] 
FCBFULL [54] 
fence [91], [93] 
fence, event 106, [91], [93] 



freld(s) 

formats 89-92 
bank-pair 14 
pointer 79 
FIFO (first-in, first-out) 109 
FILBUSY [55] 
file{s) 7-8, 52 

assembly-language code [133] 
block 50-56, 62 

allocation for sparse 98 
cail{s) 69-73, [2] 

errors 160, [125] 
character 50-56, 57 
closed 52-53 
closing before TERMINATE 

[103] 
code 145 

part of a code [135] 
control block 64 
copying sparse 98 
creating interpreter 143 
data formats of relocatable 
assembly- language code 
146 
defined 50 
directory 57-58 
format 78-92 
relocatable 120 
or absolute 143 
reading 91-92 
empty 65 

enti7 (entries) 78, 85-89 

inactive 86, 89 

sapling 89 

seedling 89 

subdirectory 89 

tree 89 
information 62-64 
input/output 67 
interpreter, creating an 1 43 
level, system 66 
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maximum capacity of a 94 
name(s) 58-59, 60 

illegal 59 

legal 59 

syntax 59 
open 52-53, 63 
operations on 68 
organization 76-99 

code [132] 
sapling 93, 95 
seedling 93,95 
SOS 56-62 
sparse 63. 94, 97-98 
standard 57-58 

locating a byte in 98-99 

storage formats of 92-99 
structure 

common 3 

hierarchical 8 

of a block 50-51 

of a character 50-51 

of a sapling 96 

of a seedling 95 

of a tree 96 
subdirectory 57, 78 
system 

relationship to device 
system 57 

root of 59 

SOS 55-62 

tree 61 
top-level 57 
tree 94, 96-97 

growing a 92-95 
type 68 

volume directory 77 
file count 82, 85 
flle'name 60, 63, 80, 83, 87 
fiiejype 64, 87. 91, [4], [13], [18] 
FIND_SEG 26,30,121,122. 

(77-79] 

flexible disk 42, 77, 93, [109 J 



floppy disk See flexible disk 

flow of control 27 

FLUSH 66, 72. [37], [41-42] 

FNFERR [54] 

form 

bank-switched 13 

current-bank-switched 13 

of a SOS call 148, 160 
format(s) 

absolute or relocatable 143 

date and time 90 

directory file 78 

of attribute table [137] 

of directory files 78 

of information on a volume 77 

of name parameter 159 

of relocatable assembly- 
language code files, data 146 

relocatable 120 

volume 77 
free memory 23 

data in 30 

obtaining 121-124 

segment allocated from 29 
(ree_blocks [23] 
•FUNG [136],[139J 
FUNCTION 145 
future versions 

compatibility with 18 

of SOS 91,92,93 

G 

general purpose communications 

(.RS232} [111] 
GET_ANALOG 113,115, 

[99-101] 

GET_DEV_NUIV1 43, 44, 45, 47, 
[65] 

GET_EOF 65,66,68,73, [49] 
GET_FENCE 110,114. [93] 
GET_FILE_INFO 63,65.68,70, 
152, [17-211 
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GET_LEVEL 66, 69, 73, [53] 
GET_MARK 66, 68, 72, [45] 
GET_PREFIX 70, [27] 
GET_SEG_INFO 26, [83-84] 
GET_SEG_NUM 26, [85] 
QET_TIME 90, 1 12, 1 15, [97-98] 
-GRAFIX [110] 
graphics 16.[110] 
area 16 

device drivers 16 
growing a tree file 92 

ft 

hand symbol xv 
handler 

event 5, 125 

interrupt 5 
handling an event 106,107 
hardware 8, 10 

independence 2 

interrupt 105 
header(s) 43, 119 

directory 78.79-82 

subdirectory 82-85,89 

volume directory 79, 80, 89 
header pointer 89 
heads 77 

hexadecimal (hex) xviii 

digit 12 

numbers xviii 
hierarchical file structure 8 
hierarchical tree structure 56, 76 
high-order nibble [117] 
highest bank 11 

pair 1 5 
highest switchable bank 15,18 
highest-numbered bank 23 
housekeeping functions 3 
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block 51 
buffer 50. 127 
character 51 
device-independent 67 
ERROR [129] 
Implementation versus interface 
76 

warning 99 
INCOMPATIBLE INTERPRETER 
[129] 

increment loop 124 

one-bank example of 124 
incrementing a pointer 36-37 
index b)ock(s) 93,94,95 
master 94 
maximum 94 
sub- 94, 96 
indexblock 99 
indexed mode, zero-page 29 
indexing 15 

addresses 15 
indirect 

addressing 10 
enhanced 10,13-16,27,30, 

31-32 
normal 14 
operation, normal 31 
pointer(s) 154, 156. 157 
with an X-byte between $80 

and S8F 158 
with an X- byte of $00 1 57 
indirect-X addressing 13 
indirect-Y addressing 13 
input(s) 

analog 113 
device 40 
parameters [116] 
input/output, file 67 
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interface versus implementation 
76 

warning 99 
interface, SOS 76 
intermediate form, bank-switched 

addresses as 32 
.tNTERP [139] 

interpreter(s) 5, 16, 118-125, 145, 
[132] 

and modules 144 

BASIC 145 

code 10 
executing 10 

command [I03j 

environment 18-19 

files, creating 143 

language 118 

maximum size of 18 

memory 
placement 18 
requirements of 146 

Pascal 145 

return to 29 

sample(s) 125-142 
listing, complete 131-142 

stand-alone 118 

structure of 119-121 

table within 29,30 
INTERPRETER FILE NOT 

FOUND [129] 
interpreter- relative relocation 

table [139] 
interpreter's 

stack 19,110 

zero page 1 9 
interrupt(s} 5,104-115 

conflicts between 104 

handler 5,22,104 

IRQ 22 
and NMI 20 

ranked in priority 104 

summar/ of 1 12 



invalid 

address 13 

jumps 29 

regions 15, 16 
INVALID DRIVER FILE [129] 
io buffer [31] 
lOERR [72] 
IRQ interrupts 20, 22 
is_newline 67,68, [33] 

J 

JMP 27-28. [139] 
joymode [99] 
joy status [100] 
joystick [99] 
JSn-B [100] 
JSn-Sw [100] 
JSn-X [100] 
JSn-Y [100] 
JSR 27-28 
jumps 29 

inside module 29 

Invalid 29 

valid 29 

K 

KERNEL FILE NOT FOUND 

[130] 

key poinler 87, 92 

keyboard 40 

L 

labels xix, 120 

local 127 
language interpreter 118 
largest possible file 94 
last_mod date and time 64, 88, 

89-90, [14], [19] 

field 89-90 
LDA 31, [139] 
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leaving ExerSOS [119] 
legal device names 42 
legal file names 59 
length 152, [3], [11], [17], 125], 

[30], [67], [116] 
letters 42, 56 
level 66. [51], [53] 
level, system file 66 
limit 23,122, [75], [78], [83] 
LIMIT 122 

line-termination character 67 

linked list 78 

linker information [133] 

linking 

assembly-language modules 
145 

dynamic loading during 1 45 
lists 

required parameter 129, 

150-152 
optional parameter 152-154 
loading 

dynamic, during linking 145 
assembly-language modules 
145 

routine [134] 
loadingaddress 120, 121 
locating a byte in a standard 

file 98 
logical 

block 77 
device 53 

byte position 98 

device(s) 40 
accessing a 41 
multiple 54 

structures 76 
logical/physical device 

correspondence 54 
loop, increment 124 
low-order nibble [117] 
LVLERR [56] 



M 

machine 
abstract 2 

storing the state of the 1 10 
macro, SOS 126 
Makelnterp [121-122] 
management calls 

device 5 

file 5 

memory 5 

utility 5 
manager, resource 2-3 
manual movement of EOF and 

mark 66 
manuf_id 45, [70] 
manufacturer 45 
mark 51 , 53, 64-65, 68, 97, 98, 

[45] 

movement of, automatic 65 
movement of, manual 65-66 

marker, current position 51 

master index block 94, 96, 97 

maximum 

number of access patiis 53 
capacity of a file 94 
number of index blocks 94 
sizeof an interpreter 18 

MCTOVFL [127] 

media, removable 53, 54 

medium 42, 53 

MEM2SML [127] 

memory 6-7, 23 

access techniques 27-38 
addressing, bank-switched 

10-13 
allocation 25, 121 
bookkeeper 7 
call(s) 25-27 
errors 160 
conflict 121 
avoiding 121 
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management 7 

calls 5 
obtaining free 121-124 
placement 

interpreter 18 

module 144 

SOS device driver 21 

SOS Kernel 20 
S-bank 19 
segment 7 
size, maximum S. 10 
unswitched 28 
messages, error [123-130] 
min_version 81 , 84, 88 
mode(s) 

absolute addressing 29 
addressing 10-16 
enhanced addressing 8 
newline information 67 
zero-page addressing 29 

indexed 29 
modification date and time 68 
module(s) 5, [132] 
absolute 143 
addressing 27-29 
assembly-language 19,118, 

143-146 

linking 145 
BASIC invokable 145 
creating 146 
driver 41 

execution, bank-switching 

for 30 
formats 146 
loader [134] 
Pascal 145 

program or data access by 1 45 
relocatable 143, 146, [132] 
multiple 

access paths 52 
logical devices 54 
volumes 54 



N 

name(s} 60, 68 
device 60 
file 58-59,60 
local 59 

parameter 159-160 

volume 55-56, 60 
name_ length 80, 83, 87 
naming conventions 76 
newpathname [9] 
NEWLINE 67, 68. 69. 71 , [33-34] 
newline 

character 67 

mode 67 
newline char 67, 68, [33] 
newline-mode information 67 
nibble 

high-order [117] 

low-order [117] 
NMI 114 

interrupts 20 
NMIHANG [1271 
NORESC [72] 
notation xvtii 

and symbols xviii 

bank-switched address 15, 
23 

extended address 15 

numeric xviii 

segment address 23-27 
NOTBLKDEV [56] 
NOTOPE^f [72] 
NOTSOS [55] 
NOWRITE [721 
null characters < ASCI I $00) 97 
number(s) 

decimal xix 

device 44 

hexadecimal xiv 

reference 52 

slot 44 
changing 46 
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unit 44 
version 45 
numeric notation xvili, xix 

a 

OPEN 52. 53. 68, 69, 71 , [29-32] 

call, example 128 
operating system 2-3 

defined 2 
operations 

asynchronous 5 

normal indirect 31 

on devices 45-46 

on files 68 

sequential read and write 50 
opt header 120 
opt header length 120 
optfonjist '152, {3],[11J, n^I, 

[29], [67] 
optional parameter list 152-154, 

[X] 

ORA 31 

order of event queue 109 
organization, code file [132] 
OUTOFMEM [56] 
output device 40 
overview of the Apple III 3-8 
OVRERR [54] 

P 

page(s) 23, [31], [78], [81]. [63] 

part of segment address 25 
parameter(s) 

format of a name 159 

input [116] 

list, 

optional 152-154, [x] 
required 129, 150-152, [x] 

name 159-160 

passing 145 

pointer 145 



parent entry length 85 
parenlentrynumber 85 
parent pointer 85 
parmcount [xi] 
parmlist 1 49 
Pascal 118, 143, [132] 

and BASIC modules 145 

assembler 145, (134] 

interpreter 145 

prefix 62 

program 145 

versus SOS prefixes 62 
path(s) 

access 52 
information 64-66 
multiple 52 

maximum number of 56 
pathname [3], [7], [9], [11]. [17], 

[25], [29] 
pathname 52, 59-61 

full 62 

partial 61-62 

syntax 60 

valid 61 
PERFORM 145 
period 42, 56 
peripheral device 8,104 
physical device 40, 54 

correspondence with logical 
devices 54 
PNFERR [54] 
point, decimal xix 
pointer(s) 31.69,152 

address extension 154-159 

byte order of 79 

comparing two 37 

direct 154, 155-156 
to current 156 
toX-bank 155 

extended 123 

fields 79 

incrementing a 36-37 
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indirect 154,156-159 

manipulation 36-38 

parameters 145 

preceding- block 78 

self-relative [136], [138] 

three-byte 98 
POSNERR [55] 
prefix(es) 60,61-62 

Pascal 62 

restrictions on 62 

SOS 62 
versus Pascal 62 
PRINTER [111] 
printers 40 
pnorityof zero 108 
priority-queue scheme 108 
PRIVATE [138] 
.PROC [136], [139] 
proceclure(s) [135], [136] 

attribute table [136] 

code [136] 

dictionary' [135] 
entries [136] 
PROCEDURE NUMBER [138] 
procedure-relative relocation 

table [139] 
processing an event 106 
Processor, Apple III xvii 
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